Skip to content

Add command to create a Swift DocC documentation catalog#2006

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

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

Conversation

@amanmaurya92

@amanmaurya92 amanmaurya92 commented Dec 17, 2025

Copy link
Copy Markdown

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

@matthewbastien matthewbastien left a comment

Copy link
Copy Markdown
Member

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.

@amanmaurya92

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.

@matthewbastien matthewbastien left a comment

Copy link
Copy Markdown
Member

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

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