Hi everyone,
I’ve implemented the **Swift: Create DocC Documentation Catalog** command for the VS Code Swift extension and would like to share how it works and ask for your review and suggestions.
- Issue: [Add a command to create a documentation catalog #1647]
- PR: [Add command to create a Swift DocC documentation catalog #2006]
What the command does
The command walks you through creating DocC documentation catalogs for one or more Swift Package Manager targets. It creates a `.docc` folder inside each chosen target’s directory (where SourceKit-LSP looks for documentation) and adds a module overview file with the correct title format.
How to run it
- Command Palette: `Swift: Create DocC Documentation Catalog` (or `Ctrl+Shift+P` / `Cmd+Shift+P` → type “Create DocC”).
- Walkthrough: Get Started with Swift for VS Code → step “Create a DocC Documentation Catalog” → “Try it out”.
---
Case 1: Single workspace folder (one Swift package)
When you have exactly one workspace folder open:
1. Run the command. No folder picker is shown; that folder is used automatically.
2. A Quick Pick lists all targets in the package (e.g. executables, libraries). You can select one or more targets.
3. For each selected target, the command creates `.docc` inside that target’s directory and adds `.md` with a module title.
Screenshot 1 – Quick Pick with targets (single folder):
Screenshot 2 – Result in Explorer (e.g. `Sources/MyLib/MyLib.docc`):
Screenshot 3 – Success message:
---
Case 2: Multiple workspace folders
When you have two or more workspace folders:
1. Run the command.
2. First, a Quick Pick asks you to choose the workspace folder where the catalog(s) should be created.
3. After you pick a folder, you see the target list for that folder’s package (same as Case 1).
4. Select one or more targets; the command creates the catalogs and shows the same success/warning messages.
Screenshot 4 – Folder selection (multi-root):
Screenshot 5 – Target selection (after folder chosen):
---
Case 3: No package / no targets
- No workspace folder open: The command shows an error: “Creating a documentation catalog requires an open workspace folder.”
- Folder has no Swift package or no targets: The command shows: “No Swift package targets found. Open a folder that contains a Package.swift.”
Screenshot 7 (optional) – Error when no targets:
---
Case 4: Catalog already exists
If you run the command again and choose a target that already has a `.docc` catalog:
- The command skips creating it again.
- A warning message lists the skipped catalog(s), e.g. “Catalog(s) already exist and were skipped: MyLib.docc”.
- Any new catalogs (for other selected targets) are still created and reported in the success message.
---
What gets created on disk
For a target named `MyLib` in `Sources/MyLib/`:
```
Sources/
MyLib/
MyLib.docc/
MyLib.md ← contains: # \`\`MyLib\`\`
(existing .swift files...)
```
The markdown uses the double-backtick title format so DocC/SourceKit-LSP recognize the module name correctly.
---
Summary of UI flow
Step. When | What you see |
1. Multiple workspace folders | Quick Pick: “Select a workspace folder to create the DocC catalog in” |
2. Always (after folder is known) | Quick Pick: “Select one or more targets to add a documentation catalog to.” (target names + type) |
3. After selection | Info: “Created DocC catalog(s): …” and/or Warning: “Catalog(s) already exist and were skipped: …” |
---
Asking for feedback
- Does this flow match what you’d expect from a “Create DocC catalog” command?
- Any suggestions for the wording of the Quick Pick titles/placeholders or the success/warning messages?
- Would you find it useful to have a “Create for all targets” option (e.g. one click to add a catalog to every target in the package)?
I’m happy to adjust the behavior or copy based on your feedback. Thanks for trying it out.
---