Add command to create a Swift DocC documentation catalog #2006
Conversation
amanthatdoescares
requested review from
0xTim,
adam-fowler and
award999
as code owners
matthewbastien
left a comment
matthewbastien
left a comment
There was a problem hiding this comment.
Thank you for this PR! There are a few issues that need to be resolved before this can be merged.
| @@ -0,0 +1,40 @@ | |||
| import * as fs from "fs"; | |||
There was a problem hiding this comment.
issue: Missing copyright header.
| return; // user cancelled | ||
| } | ||
|
|
||
| const rootPath = folders[0].uri.fsPath; |
There was a problem hiding this comment.
issue: We can't assume there will only be a single workspace folder. The command should guide the user through creating a catalog in any workspace folder they wish to use.
| export async function createDocumentationCatalog(): Promise<void> { | ||
| const folders = vscode.workspace.workspaceFolders; | ||
| if (!folders || folders.length === 0) { | ||
| await vscode.window.showErrorMessage("Open a workspace first."); |
There was a problem hiding this comment.
issue: This error message is a bit vague. Can we change it to something like Creating a documentation catalog requires that a folder or workspace be opened?
suggestion: We can also make it less likely for this situation to occur by only showing swift.createDocumentationCatalog in the command palette if a workspace is present. See the other commands with when clauses in the package.json for examples.
| } | ||
|
|
||
| const rootPath = folders[0].uri.fsPath; | ||
| const doccDir = path.join(rootPath, `${moduleName}.docc`); |
There was a problem hiding this comment.
issue: We can't assume that the user will only place a catalog at the root of the workspace. Documentation catalogs can be located anywhere in the project structure. However, they are most commonly placed within targets from the Package.swift to provide documentation for them. I would show a quick pick with the available targets and an option at the end for creating a standalone documentation catalog.
| const doccDir = path.join(rootPath, `${moduleName}.docc`); | ||
| const markdownFile = path.join(doccDir, `${moduleName}.md`); | ||
|
|
||
| if (fs.existsSync(doccDir)) { |
There was a problem hiding this comment.
suggestion: We can show this error in the input and not allow continuing instead of forcing the user to restart the whole command. See the create new project command for an example of this.
2 participants
Description
This change adds a new Swift command that helps users get started with DocC documentation.
The command prompts for a module name and creates a basic DocC catalog in the workspace, including:
<Module>.doccdirectoryThis removes the need to manually set up the DocC folder structure and makes it easier to start documenting Swift packages directly from VS Code.
Issue: #1647
Tasks