Add command to create a Swift DocC documentation catalog #2006

amanthatdoescares · 2025-12-17T08:39:37Z

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:

A <Module>.docc directory
An initial markdown file with the module title

This 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

Required tests have been written
Documentation has been updated (not applicable)
Added an entry to CHANGELOG.md if applicable

matthewbastien

Thank you for this PR! There are a few issues that need to be resolved before this can be merged.

src/commands/createDocumentationCatalog.ts

…gue error message, changed await to void

src/commands/createDocumentationCatalog.ts

Co-authored-by: Matthew Bastien <matthew_bastien@apple.com>

plemarquand · 2025-12-18T13:46:00Z

src/commands/createDocumentationCatalog.ts

+
+    if (hasPackageSwift) {
+        try {
+            const { stdout } = await execFileAsync("swift", ["package", "dump-package"], {


This information is already computed and stored on the folderContext.swiftPackage for each Swift Package folder open in the workspace. See https://github.com/swiftlang/vscode-swift/blob/main/src/commands.ts#L80 for a reference of how to get the folderContext for the currently active folder and pass it in to the command.

Thanks for pointing this out — I wasn’t aware this information was already available via FolderContext. I’ll refactor the command to use folderContext.swiftPackage instead of invoking swift package dump-package.

plemarquand · 2025-12-18T13:46:50Z

src/commands/createDocumentationCatalog.ts

+    for (const name of targets) {
+        const srcPath = path.join(rootPath, "Sources", name);
+        try {
+            await fs.access(srcPath);


you can use fileExists in utilities/filesystem instead

once i read filesystem i think folderExists is much more accurate in this case

fileExists() and folderExists() check for the path in question to be a file or folder respectively. You're going to want to use pathExists() because you can't create the folder if anything exists at that path regardless of whether or not it is a file, folder, symlink, etc.

@matthewbastien Target discovery still uses folderExists() since those must be directories.

plemarquand · 2025-12-18T13:47:13Z

src/commands/createDocumentationCatalog.ts

+
+            const doccDir = path.join(basePath, `${value}.docc`);
+            try {
+                await fs.access(doccDir);


fileExists here as well

i think folderExists is much accurate here

You'll have to use pathExists().

Yes, i have made that commit now

matthewbastien · 2025-12-19T16:29:22Z

I'd also like to have an integration test for this since the logic will be interacting with the FolderContext. Something that runs the command and makes sure that all of the targets show up correctly in the quick pick. It should also make sure that the catalog gets created properly.

amanthatdoescares · 2025-12-20T04:54:14Z

@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.

matthewbastien · 2025-12-22T02:16:49Z

test/integration-tests/commands/createDocumentationCatalog.test.ts

+        },
+    });
+
+    test("creates a DocC catalog for a SwiftPM target", async () => {


issue: The nested test() is unnecessary and will make it so that this test never actually runs.

matthewbastien · 2025-12-22T02:19:08Z

test/integration-tests/commands/createDocumentationCatalog.test.ts

+import { tag } from "../../tags";
+import { activateExtensionForSuite, folderInRootWorkspace } from "../utilities/testutilities";
+
+tag("large").suite("Create Documentation Catalog Command", function () {


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.

matthewbastien · 2025-12-22T02:20:39Z

src/commands/createDocumentationCatalog.ts

+//
+// Copyright (c) 2025 the VS Code Swift project authors
+// Licensed under Apache License v2.0
+//


issue: This is missing part of the copyright header.

matthewbastien · 2025-12-22T05:31:32Z

test/integration-tests/commands/createDocumentationCatalog.test.ts

+// This source file is part of the VS Code Swift open source project
+//
+// Copyright (c) 2025 the VS Code Swift project authors
+// Licensed under Apache License v2.0


issue: This is missing part of the copyright header.

matthewbastien · 2025-12-22T05:32:56Z

src/commands/createDocumentationCatalog.ts

+    const basePath = selection.basePath;
+
+    // ---- module name input ----
+    const moduleName = await vscode.window.showInputBox({


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.

matthewbastien · 2025-12-22T05:41:41Z

test/integration-tests/commands/createDocumentationCatalog.test.ts

+                expect(await fs.stat(markdownFile)).to.exist;
+
+                const contents = await fs.readFile(markdownFile, "utf8");
+                expect(contents).to.contain("# MyModule");


issue: The module name when selecting a target should match the module name of that target.

matthewbastien · 2025-12-22T05:42:34Z

test/integration-tests/commands/createDocumentationCatalog.test.ts

+            }
+        });
+    });
+});


suggestion: We should also test the logic for creating a standalone documentation catalog.

matthewbastien · 2025-12-22T05:47:05Z

test/integration-tests/commands/createDocumentationCatalog.test.ts

+
+    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");


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"); }); });

matthewbastien · 2025-12-22T05:48:54Z

test/integration-tests/commands/createDocumentationCatalog.test.ts

+            const inputBoxStub = sinon.stub(vscode.window, "showInputBox");
+
+            try {
+                inputBoxStub.resolves("MyModule");


issue: The module name quick pick should not be shown if selecting a target.

src/commands/createDocumentationCatalog.ts

Co-authored-by: Matthew Bastien <matthew_bastien@apple.com>

amanthatdoescares added 2 commits December 17, 2025 14:01

Add command to create Swift DocC documentation catalog

43e2518

Add command to create Swift DocC documentation catalog

81461d5

amanthatdoescares requested review from 0xTim, adam-fowler and award999 as code owners December 17, 2025 08:39

restoring package-lock-json

6291552

matthewbastien requested changes Dec 17, 2025

View reviewed changes

award999 reviewed Dec 17, 2025

View reviewed changes

src/commands/createDocumentationCatalog.ts Outdated Show resolved Hide resolved

award999 reviewed Dec 17, 2025

View reviewed changes

src/commands/createDocumentationCatalog.ts Outdated Show resolved Hide resolved

amanthatdoescares added 3 commits December 18, 2025 05:14

Use async filesystem APIs, Included Copyright Headers, changed the va…

3277a02

…gue error message, changed await to void

Validate Docc Catalog exisitance inside input

a528243

Ask user to select the workspace folder and validate docc name inline

62a4225

matthewbastien requested changes Dec 18, 2025

View reviewed changes

amanthatdoescares and others added 4 commits December 18, 2025 12:13

Update src/commands/createDocumentationCatalog.ts

907fdfb

Co-authored-by: Matthew Bastien <matthew_bastien@apple.com>

Update src/commands/createDocumentationCatalog.ts

1a6fb2f

Co-authored-by: Matthew Bastien <matthew_bastien@apple.com>

Use async filesystem check

7343dae

Add target-based QuickPick for DocC catalog creation

dd3533b

plemarquand reviewed Dec 18, 2025

View reviewed changes

amanthatdoescares added 2 commits December 19, 2025 07:41

Use folderExists for directory check

3a1d262

Using folderContext.swiftpackage

3ec91e0

amanthatdoescares added 2 commits December 20, 2025 09:32

Use pathExists for DocC creation checks

d74fb7c

Add integration test for createDocumentationCatalog command

3b8853c

matthewbastien requested changes Dec 22, 2025

View reviewed changes

amanthatdoescares and others added 2 commits December 22, 2025 12:37

Update src/commands/createDocumentationCatalog.ts

2410af8

Co-authored-by: Matthew Bastien <matthew_bastien@apple.com>

remove nested test, mark suite as small, added right header

f991a9c

Add command to create a Swift DocC documentation catalog #2006

Are you sure you want to change the base?

Add command to create a Swift DocC documentation catalog #2006

Conversation

amanthatdoescares commented Dec 17, 2025 • edited by matthewbastien Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Tasks

Uh oh!

matthewbastien left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

matthewbastien Dec 19, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

matthewbastien commented Dec 19, 2025

Uh oh!

amanthatdoescares commented Dec 20, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

amanthatdoescares commented Dec 17, 2025 •

edited by matthewbastien

Loading

matthewbastien Dec 19, 2025 •

edited

Loading