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.
Co-authored-by: Matthew Bastien <[email protected]>
Co-authored-by: Matthew Bastien <[email protected]>
|
I'd also like to have an integration test for this since the logic will be interacting with the |
|
@matthewbastien I’ve added an integration test that runs the command end-to-end, verifies SwiftPM targets appear in the QuickPick, and asserts the DocC catalog is created on disk. This is my first time writing an integration test in this codebase, so I’d really appreciate a review on the test structure and coverage. |
test/integration-tests/commands/createDocumentationCatalog.test.ts
Outdated
Show resolved
Hide resolved
| import { tag } from "../../tags"; | ||
| import { activateExtensionForSuite, folderInRootWorkspace } from "../utilities/testutilities"; | ||
|
|
||
| tag("large").suite("Create Documentation Catalog Command", function () { |
There was a problem hiding this comment.
issue: This suite should be marked as either "medium" or "small". It definitely doesn't need 10 minutes just to create a directory. I'm leaning towards "small" in this instance since it really shouldn't take long at all.
There was a problem hiding this comment.
i changed it to small
| const basePath = selection.basePath; | ||
|
|
||
| // ---- module name input ---- | ||
| const moduleName = await vscode.window.showInputBox({ |
There was a problem hiding this comment.
issue: By convention the module name for a target should match the target name if the user selected one in the previous step. The extension should only ask for a folder if the user selected a standalone documentation catalog.
| expect(await fs.stat(markdownFile)).to.exist; | ||
|
|
||
| const contents = await fs.readFile(markdownFile, "utf8"); | ||
| expect(contents).to.contain("# MyModule"); |
There was a problem hiding this comment.
issue: The module name when selecting a target should match the module name of that target.
|
|
||
| test("creates a DocC catalog for a SwiftPM target", async () => { | ||
| test("creates a DocC catalog for a SwiftPM target", async () => { | ||
| const quickPickStub = sinon.stub(vscode.window, "showQuickPick"); |
There was a problem hiding this comment.
suggestion: We have methods in MockUtils.ts that will do this for you using mocha's setup() and teardown() blocks. You don't need to use sinon.stub() or the try {} finally {} here. For example:
import { mockGlobalObject } from "../../MockUtils.ts";
suite("some-suite", () => {
const windowMock = mockGlobalObject(vscode, "window");
test("some-test", () => {
windowMock.showQuickPick.resolves("blah");
});
});| const inputBoxStub = sinon.stub(vscode.window, "showInputBox"); | ||
|
|
||
| try { | ||
| inputBoxStub.resolves("MyModule"); |
There was a problem hiding this comment.
issue: The module name quick pick should not be shown if selecting a target.
4 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