Add command to create a Swift DocC documentation catalog

package.json

@@ -489,6 +489,11 @@
         "command": "swift.generateSourcekitConfiguration",
         "title": "Generate SourceKit-LSP Configuration",
         "category": "Swift"
+      },
+      {
+        "command": "swift.createDocumentationCatalog",
+        "title": "Create Documentation Catalog",
+        "category": "Swift"
       }
     ],
     "configuration": [
@@ -1382,6 +1387,10 @@
         {
           "command": "swift.play",
           "when": "false"
+        },
+        {
+          "command": "swift.createDocumentationCatalog",
+          "when": "workspaceFolderCount > 0"
         }
       ],
       "editor/context": [

src/commands.ts

@@ -20,6 +20,7 @@ import { WorkspaceContext } from "./WorkspaceContext";
 import { attachDebugger } from "./commands/attachDebugger";
 import { cleanBuild, debugBuild, runBuild } from "./commands/build";
 import { captureDiagnostics } from "./commands/captureDiagnostics";
+import { createDocumentationCatalog } from "./commands/createDocumentationCatalog";
 import { createNewProject } from "./commands/createNewProject";
 import { editDependency } from "./commands/dependencies/edit";
 import { resolveDependencies } from "./commands/dependencies/resolve";
@@ -350,6 +351,10 @@ export function register(ctx: WorkspaceContext): vscode.Disposable[] {
             await vscode.commands.executeCommand("vscode.open", vscode.Uri.file(packagePath));
         }),
         vscode.commands.registerCommand("swift.openDocumentation", () => openDocumentation()),
+        vscode.commands.registerCommand(
+            "swift.createDocumentationCatalog",
+            async () => await createDocumentationCatalog(ctx)
+        ),
         vscode.commands.registerCommand(
             Commands.GENERATE_SOURCEKIT_CONFIG,
             async () => await generateSourcekitConfiguration(ctx)

src/commands/createDocumentationCatalog.ts

@@ -0,0 +1,150 @@
+//===----------------------------------------------------------------------===//
+//
+// 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
+//
+// SPDX-License-Identifier: Apache-2.0
+//
+//===----------------------------------------------------------------------===//
+import * as fs from "fs/promises";
+import * as path from "path";
+import * as vscode from "vscode";
+
+import { FolderContext } from "../FolderContext";
+import { WorkspaceContext } from "../WorkspaceContext";
+import { selectFolder } from "../ui/SelectFolderQuickPick";
+import { folderExists, pathExists } from "../utilities/filesystem";
+
+type DoccLocationPickItem = vscode.QuickPickItem & {
+    basePath: string;
+    targetName?: string;
+};
+
+export async function createDocumentationCatalog(
+    ctx: WorkspaceContext,
+    folderContext?: FolderContext
+): Promise<void> {
+    let folder = folderContext ?? ctx.currentFolder;
+
+    // ---- workspace folder resolution (standard pattern) ----
+    if (!folder) {
+        if (ctx.folders.length === 0) {
+            void vscode.window.showErrorMessage(
+                "Creating a documentation catalog requires an open workspace folder."
+            );
+            return;
+        }
+
+        if (ctx.folders.length === 1) {
+            folder = ctx.folders[0];
+        } else {
+            const selected = await selectFolder(
+                ctx,
+                "Select a workspace folder to create the DocC catalog in",
+                { all: "" }
+            );
+            if (selected.length !== 1) {
+                return;
+            }
+            folder = selected[0];
+        }
+    }
+
+    const rootPath = folder.folder.fsPath;
+
+    // ---- build QuickPick items from swiftPackage (PROMISE) ----
+    const itemsPromise = (async () => {
+        const items: DoccLocationPickItem[] = [];
+
+        if (folder.swiftPackage) {
+            const targets = await folder.swiftPackage.getTargets();
+
+            for (const target of targets) {
+                const base = path.join(rootPath, target.path);
+                if (await folderExists(base)) {
+                    items.push({
+                        label: `Target: ${target.name}`,
+                        description: target.type,
+                        detail: target.path,
+                        basePath: base,
+                        targetName: target.name,
+                    });
+                }
+            }
+        }
+
+        items.push({
+            label: "Standalone documentation catalog",
+            description: "Workspace root",
+            basePath: rootPath,
+        });
+
+        return items;
+    })();
+
+    // ---- show QuickPick (toolchain-style pattern) ----
+    const selection = await vscode.window.showQuickPick(itemsPromise, {
+        title: "Create DocC Documentation Catalog",
+        placeHolder: "Select where to create the documentation catalog.",
+        canPickMany: false,
+    });
+
+    if (!selection) {
+        return;
+    }
+
+    const basePath = selection.basePath;
+
+    // ---- module name input ----
+    let moduleName: string;
+
+    if (selection.targetName) {
+        // Target-based DocC: module name must match target
+        moduleName = selection.targetName;
+    } else {
+        // Standalone DocC: ask user
+        const input = await vscode.window.showInputBox({
+            prompt: "Enter Swift module name",
+            placeHolder: "MyModule",
+            validateInput: async value => {
+                const name = value.trim();
+                if (name.length === 0) {
+                    return "Module name cannot be empty";
+                }
+
+                const doccDir = path.join(basePath, `${name}.docc`);
+                if (await pathExists(doccDir)) {
+                    return `Documentation catalog "${name}.docc" already exists`;
+                }
+
+                return undefined;
+            },
+        });
+
+        if (!input) {
+            return;
+        }
+
+        moduleName = input.trim();
+    }
+
+    const doccDir = path.join(basePath, `${moduleName}.docc`);
+    const markdownFile = path.join(doccDir, `${moduleName}.md`);
+
+    // ---- execution-time guard (race-safe) ----
+    if (await pathExists(doccDir)) {
+        void vscode.window.showErrorMessage(
+            `Documentation catalog "${moduleName}.docc" already exists`
+        );
+        return;
+    }
+
+    await fs.mkdir(doccDir);
+    await fs.writeFile(markdownFile, `# ${moduleName}\n`, "utf8");
+
+    void vscode.window.showInformationMessage(
+        `Created DocC documentation catalog: ${moduleName}.docc`
+    );
+}

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

@@ -0,0 +1,93 @@
+//===----------------------------------------------------------------------===//
+//
+// 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
+//
+// See LICENSE.txt for license information
+// See CONTRIBUTORS.txt for the list of VS Code Swift project authors
+//
+// SPDX-License-Identifier: Apache-2.0
+//
+//===----------------------------------------------------------------------===//
+import { expect } from "chai";
+import * as fs from "fs/promises";
+import * as path from "path";
+import * as vscode from "vscode";
+
+import { FolderContext } from "@src/FolderContext";
+import { WorkspaceContext } from "@src/WorkspaceContext";
+
+import { mockGlobalObject } from "../../MockUtils";
+import { tag } from "../../tags";
+import { activateExtensionForSuite, folderInRootWorkspace } from "../utilities/testutilities";
+
+tag("small").suite("Create Documentation Catalog Command", function () {
+    let folderContext: FolderContext;
+    let workspaceContext: WorkspaceContext;
+    let windowMock: ReturnType<typeof mockGlobalObject>;
+
+    activateExtensionForSuite({
+        async setup(ctx) {
+            workspaceContext = ctx;
+            folderContext = await folderInRootWorkspace("defaultPackage", workspaceContext);
+            await workspaceContext.focusFolder(folderContext);
+        },
+    });
+
+    setup(() => {
+        windowMock = mockGlobalObject(vscode, "window");
+    });
+
+    teardown(() => {
+        windowMock.restore();
+    });
+
+    test("creates a DocC catalog for a SwiftPM target", async () => {
+        let selectedTargetLabel: string | undefined;
+
+        windowMock.showQuickPick.callsFake(
+            async (itemsOrPromise: vscode.QuickPickItem[] | Thenable<vscode.QuickPickItem[]>) => {
+                const items = await Promise.resolve(itemsOrPromise);
+                const target = items.find(item => item.label.startsWith("Target:"));
+                selectedTargetLabel = target?.label;
+                return target;
+            }
+        );
+
+        // This path must not prompt for a module name
+        windowMock.showInputBox.rejects(new Error("showInputBox should not be called"));
+
+        await vscode.commands.executeCommand("swift.createDocumentationCatalog");
+
+        const basePath = folderContext.folder.fsPath;
+        const moduleName = selectedTargetLabel!.replace("Target: ", "");
+        const doccDir = path.join(basePath, `${moduleName}.docc`);
+        const markdownFile = path.join(doccDir, `${moduleName}.md`);
+
+        expect(await fs.stat(doccDir)).to.exist;
+        expect(await fs.stat(markdownFile)).to.exist;
+
+        const contents = await fs.readFile(markdownFile, "utf8");
+        expect(contents).to.contain(`# ${moduleName}`);
+    });
+
+    test("creates a standalone DocC catalog when no SwiftPM target is selected", async () => {
+        windowMock.showQuickPick.resolves(undefined);
+        windowMock.showInputBox.resolves("StandaloneModule");
+
+        await vscode.commands.executeCommand("swift.createDocumentationCatalog");
+
+        const basePath = folderContext.folder.fsPath;
+        const moduleName = "StandaloneModule";
+        const doccDir = path.join(basePath, `${moduleName}.docc`);
+        const markdownFile = path.join(doccDir, `${moduleName}.md`);
+
+        expect(await fs.stat(doccDir)).to.exist;
+        expect(await fs.stat(markdownFile)).to.exist;
+
+        const contents = await fs.readFile(markdownFile, "utf8");
+        expect(contents).to.contain(`# ${moduleName}`);
+    });
+});