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.