Skip to content

Add command to create a Swift DocC documentation catalog#2006

Open
amanthatdoescares wants to merge 3 commits into
swiftlang:mainfrom
amanthatdoescares:add-docc-command
Open

Add command to create a Swift DocC documentation catalog#2006
amanthatdoescares wants to merge 3 commits into
swiftlang:mainfrom
amanthatdoescares:add-docc-command

Conversation

@amanthatdoescares
Copy link
Copy Markdown

@amanthatdoescares amanthatdoescares commented Dec 17, 2025

Description

Add command to create DocC documentation catalog (#1647)

  • Add Swift: Create DocC Documentation Catalog command that lets users
    select one or more SwiftPM targets and creates a .docc catalog inside
    each target's directory (SourceKit-LSP discovers docs there).
  • Module markdown uses title format # ModuleName per maintainer.
  • Register command in register(WorkspaceContext); add unit tests.

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

Copy link
Copy Markdown
Member

@matthewbastien matthewbastien left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Comment thread src/commands/createDocumentationCatalog.ts Outdated
Comment thread src/commands/createDocumentationCatalog.ts Outdated
Comment thread src/commands/createDocumentationCatalog.ts Outdated
Comment thread src/commands/createDocumentationCatalog.ts Outdated
Comment thread src/commands/createDocumentationCatalog.ts Outdated
Comment thread src/commands/createDocumentationCatalog.ts Outdated
Comment thread src/commands/createDocumentationCatalog.ts Outdated
Comment thread src/commands/createDocumentationCatalog.ts Outdated
Comment thread src/commands/createDocumentationCatalog.ts Outdated
Comment thread src/commands/createDocumentationCatalog.ts Outdated
Comment thread src/commands/createDocumentationCatalog.ts Outdated
Comment thread src/commands/createDocumentationCatalog.ts Outdated
Comment thread src/commands/createDocumentationCatalog.ts Outdated
Comment thread src/commands/createDocumentationCatalog.ts Outdated
@matthewbastien
Copy link
Copy Markdown
Member

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
Copy link
Copy Markdown
Author

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

Comment thread test/integration-tests/commands/createDocumentationCatalog.test.ts Outdated
Comment thread test/integration-tests/commands/createDocumentationCatalog.test.ts Outdated
Comment thread src/commands/createDocumentationCatalog.ts
Comment thread test/integration-tests/commands/createDocumentationCatalog.test.ts Outdated
Comment thread src/commands/createDocumentationCatalog.ts Outdated
Comment thread test/integration-tests/commands/createDocumentationCatalog.test.ts Outdated
Comment thread test/integration-tests/commands/createDocumentationCatalog.test.ts Outdated
Comment thread test/integration-tests/commands/createDocumentationCatalog.test.ts Outdated
Comment thread test/integration-tests/commands/createDocumentationCatalog.test.ts Outdated
Comment thread src/commands/createDocumentationCatalog.ts Outdated
- Add Swift: Create DocC Documentation Catalog command that lets users
  select one or more SwiftPM targets and creates a .docc catalog inside
  each target's directory (SourceKit-LSP discovers docs there).
- Module markdown uses title format # ModuleName per maintainer.
- Register command in register(WorkspaceContext); add unit tests.
Copy link
Copy Markdown
Member

@matthewbastien matthewbastien left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looking much better, but there are a bunch of areas where the code is more complicated than it needs to be.

Comment thread test/unit-tests/commands/createDocumentationCatalog.test.ts
Comment thread test/unit-tests/commands/createDocumentationCatalog.test.ts Outdated
Comment thread test/unit-tests/commands/createDocumentationCatalog.test.ts
Comment thread test/unit-tests/commands/createDocumentationCatalog.test.ts Outdated
Comment thread src/commands/createDocumentationCatalog.ts Outdated
Comment thread src/commands/createDocumentationCatalog.ts Outdated
Comment thread src/commands/createDocumentationCatalog.ts Outdated
@amanthatdoescares
Copy link
Copy Markdown
Author

@matthewbastien i have implemented the changes and it is ready for another review.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants