Swift-DocC is a documentation compiler for Swift frameworks and packages aimed at making it easy to write and publish great developer documentation.
Swift-DocC is being actively developed. For more information about the Swift-DocC project, see the introductory blog post here.
The latest documentation for the Swift-DocC project is available on Swift.org.
The Swift Forums are the best place to get help with Swift-DocC and discuss future plans.
If you're looking to write and publish documentation with Swift-DocC, the best way to get started is with Swift-DocC's user documentation.
Swift-DocC builds documentation by combining Symbol Graph files containing API information
.docc Documentation Catalog containing articles and tutorials
to create a final archive containing the compiled documentation.
More concretely, Swift-DocC understands the following kinds of inputs:
Symbol Graph files with the
Symbol Graph files are a machine-readable representation of a module's APIs,
including their documentation comments and relationship with one another.
A Documentation Catalog with the
Documentation Catalogs can include additional documentation content like the following:
Documentation markup files with the
.md extension. Documentation markup files can
be used to extend documentation for symbols and to write free-form articles.
Tutorial files with the
.tutorial extension. Tutorial files are used to author
step-by-step instructions on how to use a framework.
Additional documentation assets with known extensions like
Info.plist file containing metadata such as the name of the documented module.
This file is optional and the information it contains can be passed via the command line.
Swift-DocC outputs a machine-readable archive of the compiled documentation. This archive contains render JSON files, which fully describe the contents of a documentation page and can be processed by a renderer such as Swift-DocC-Render.
For more in-depth technical information about Swift-DocC, please refer to the project's technical documentation:
As of Swift 5.5, the Swift Compiler is able to emit Symbol Graph files as part of the compilation process.
SymbolKit is a Swift package containing the specification and reference model for the Symbol Graph File Format.
Swift Markdown is a Swift package for parsing, building, editing, and analyzing Markdown documents. It includes support for the Block Directive elements that Swift-DocC's tutorial files rely on.
Swift-DocC-Render is a web application that understands and renders Swift-DocC's render JSON format.
Xcode consists of a suite of tools that developers use to build apps for Apple platforms. Beginning with Xcode 13, Swift-DocC is integrated into Xcode with support for building and viewing documentation for your framework and its dependencies.
docc is the command line interface (CLI) for Swift-DocC and provides
support for converting and previewing DocC documentation.
DocC is a Swift package. If you're new to Swift package manager, the documentation here provides an explanation of how to get started and the software you'll need installed.
DocC requires Swift 5.5 which is included in Xcode 13.
Checkout this repository using:
git clone https://github.com/apple/swift-docc.git
Navigate to the root of the repository with:
Finally, build DocC by running:
docc, run the following command:
swift run docc
You can test a locally built version of Swift-DocC in Xcode 13 or later by setting
DOCC_EXEC build setting to the path of your local
Select the project in the Project Navigator.
In the Build Settings tab, click '+' and then 'Add User-Defined Setting'.
Create a build setting
DOCC_EXEC with the value set to
The next time you invoke a documentation build with the "Build Documentation"
button in Xcode's Product menu, your custom
docc will be used for the build.
You can confirm that your custom
docc is being used by opening the latest build
log in Xcode's report navigator and expanding the "Compile documentation" step.
doccto build and preview documentation
You can use
docc directly to build documentation for your Swift framework
or package. The below instructions use this repository as an example but
apply to any Swift package. Just replace any reference to
with the name of your package.
Begin by navigating to the root of your Swift package.
Then run the following to generate Symbol Graph files for your target:
mkdir -p .build/symbol-graphs && \ swift build --target SwiftDocC \ -Xswiftc -emit-symbol-graph \ -Xswiftc -emit-symbol-graph-dir -Xswiftc .build/symbol-graphs
You should now have a number of
.symbols.json files in
representing the provided target and its dependencies. You can copy out the files representing
just the target itself with:
mkdir .build/swift-docc-symbol-graphs \ && mv .build/symbol-graphs/SwiftDocC* .build/swift-docc-symbol-graphs
The best place to get started with Swift-DocC-Render is with the instructions in the project's README.
If you have Xcode 13 or later installed, you can use the version of Swift-DocC-Render that comes included in Xcode with:
export DOCC_HTML_DIR="$(dirname $(xcrun --find docc))/../share/docc/render"
Alternatively, you can clone the Swift-DocC-Render-Artifact repository and use a recent pre-built copy of the renderer:
git clone https://github.com/apple/swift-docc-render-artifact.git
Then point the
DOCC_HTML_DIR environment variable
to the repository's
docc preview command performs a conversion of your documentation and
starts a local web server to allow for easy previewing of the built documentation.
It monitors the provided Documentation Catalog for changes and updates the preview
as you're working.
docc preview Sources/SwiftDocC/SwiftDocC.docc \ --fallback-display-name SwiftDocC \ --fallback-bundle-identifier org.swift.SwiftDocC \ --fallback-bundle-version 1.0.0 \ --additional-symbol-graph-dir .build/swift-docc-symbol-graphs
You should now see the following in your terminal:
Input: ~/Developer/swift-docc/Sources/SwiftDocC/SwiftDocC.docc Template: ~/Developer/swift-docc-render-artifact/dist ======================================== Starting Local Preview Server Address: http://localhost:8000/documentation/swiftdocc ======================================== Monitoring ~/Developer/swift-docc/Sources/SwiftDocC/SwiftDocC.docc for changes...
And if you navigate to http://localhost:8000/documentation/swiftdocc you'll see
the rendered documentation for
Swift-DocC's CLI tool (
docc) will be integrated into the Swift toolchain
and follows the Swift compiler's versioning scheme.
SwiftDocC library is versioned separately from
SwiftDocC is under
active development and source stability is not guaranteed.
Note: You can use the
environmentscript in this repository to gather helpful environment information to paste into your bug report by running the following:
If you can confirm that the bug occurs when using the latest commit of Swift-DocC
main branch (see Building Swift-DocC),
that will help us track down the bug faster.
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.
Please see the contributing guide for more information.
|Last commit: 31 minutes ago|