swift-docc_skill

Overview

This skill helps you create DocC documentation for iOS 17+/macOS 14+ Swift projects. It covers adding /// documentation comments, building a DocC catalog, authoring articles and tutorials, and publishing static documentation to GitHub Pages. Use it to produce clear API docs, interactive tutorials, and CI-driven hosting pipelines.

How this skill works

I guide you through placing documentation comments on public symbols, structuring a Documentation.docc catalog inside your target, and writing landing pages, articles, and tutorials. I also show how to build and preview docs in Xcode, generate static site output with the Swift Package Manager, and wire up a GitHub Actions workflow to deploy to GitHub Pages.

When to use it

• You need to document public and open Swift APIs with /// comments
• You want to create a DocC catalog (Sources/<Target>/Documentation.docc)
• You want to add articles or interactive tutorials to your docs
• You need instructions to generate static docs with swift package generate-documentation
• You want a CI workflow to publish documentation to GitHub Pages

Best practices

• Document every public/open symbol and include examples for complex APIs
• Explain the intent and "why" in addition to behavior and parameters
• Use callouts (Important, Warning, Tip) for lifecycle and safety notes
• Organize the catalog: landing page, articles, Tutorials/, Resources/ (images)
• Keep documentation in sync with code and include usage snippets for clarity

Example use cases

• Convert /// comments into a Documentation.docc catalog and brief landing page
• Add parameter, returns, throws, and note sections to an async API
• Create an interactive tutorial (.tutorial) that walks users through common flows
• Set up swift package generate-documentation in CI and publish output to GitHub Pages
• Preview docs locally with Xcode Developer Documentation or swift package preview-documentation