apple/swift-docc

Documentation compiler that produces rich API reference documentation and interactive tutorials for your Swift framework or package.

Swift-DocC

Swift-DocC is a documentation compiler for Swift frameworks and packages aimed at making it easy to write and publish great developer documentation

For an example of Swift-DocC in action, check out developer.apple.com. Much of Apple's developer documentation, from Reference documentation to Tutorials, and long-form content is built using Swift-DocC.

To learn more about the essentials of this tool refer to the user documentation.

Swift-DocC is being actively developed. For more information about the Swift-DocC project, see the introductory blog post here.

Contributing to Swift-DocC

The Swift Forums are the best place to get help with Swift-DocC and discuss future plans.

As an open-source project, we value any contribution made to this tool. Please see the contributing guide for more information on how to contribute and build DocC from source.

Getting Started with DocC

docc is the command line interface (CLI) for Swift-DocC and provides support for generating and previewing documentation.

There are multiple ways you can make use of DocC depending on your use case:

1. For documenting packages via SwiftPM:

If you want to generate documentation for your Swift package we recommend using the Swift-DocC Plugin. Please refer to the Plugin's documentation to get started with building, previewing, and publishing your documentation to your website or GitHub Pages.

2. For standalone documentation:

If you have Xcode installed, it's recommended to generate documentation using the xcrun command. You can get DocC working by invoking xcrun docc in your terminal.

Swift-DocC is also included in the Swift toolchain for both macOS and Linux.

To see instructions on how to use DocC from the CLI run

docc --help

3. For documenting apps, frameworks, and packages using Xcode:

If you want to generate an API reference for your project you can use DocC via Xcode. Please refer to the Xcode documentation to learn the essentials of how to get started.

Writing and Publishing Documentation with Swift-DocC

If you want to learn how to write and format your documentation please refer to Formatting Your Documentation Content. For publishing go to Distributing Documentation to Other Developers.

To learn more about how Swift-DocC works internally please see CONTRIBUTING.md.

Versioning

Swift-DocC's CLI tool (docc) is integrated into the Swift toolchain and follows the Swift compiler's versioning scheme.

The SwiftDocC library is versioned separately from docc. SwiftDocC is under active development and source stability is not guaranteed.

Bug Reports and Feature Requests

Submitting a Bug Report

Swift-DocC tracks all bug reports with GitHub Issues. When you submit a bug report we ask that you follow the provided template and provide as many details as possible.

Note: You can use the environment script in this repository to gather helpful environment information to paste into your bug report by running the following:

bin/environment

If you can confirm that the bug occurs when using the latest commit of Swift-DocC from the main branch (see Building Swift-DocC), it will help us track down the bug faster..

Submitting a Feature Request

For feature requests, please feel free to file a GitHub issue or start a discussion on the Swift Forums.

Don't hesitate to submit a feature request if you see a way Swift-DocC can be improved to better meet your needs.

All user-facing features must be discussed in the Swift Forums before being enabled by default.