Swift-DocC is Now Open Source

At WWDC21, Apple announced Swift-DocC, a new documentation compiler for Swift frameworks and
packages. Swift-DocC provides an effortless way to author great documentation alongside your code,
and generate comprehensive documentation websites for Swift codebases. It supports API docs authored
as code comments, long-form conceptual articles written in Markdown, and even step-by-step tutorials
with integrated images.

Swift-DocC is included in the Xcode 13 tools, and people are already adding more documentation
to their code. When it was announced at WWDC21, some of the engineers mentioned that Swift-DocC will
be released as open source. And that day is now here, with support for multiple platforms.

Swift-DocC was developed with the following goals:

• Integrate with existing development tools. The Swift-DocC tooling was
  built to seamlessly integrate into existing developer workflows, and to work
  directly within popular coding tools and IDEs. Using Swift-DocC to author
  documentation will easily fit into the same version control process that
  developers already use.
• Simplify authoring rich reference documentation. Reference documentation
  is an important resource for describing the behavior of your API, and best
  practices for third-party developers. Often the links among APIs are critical
  to explaining their use, so making these links easy to author and validate was
  a key goal.
• Encourage high-level technical articles. Historically, developers
  authored and maintained high-level educational documents separately from API
  documentation, making this content less likely to be written in the first
  place, and likely to fall out of date. By providing facilities for authoring
  this high-level content right alongside the code, and for easy inter-linking of
  API and conceptual docs, the goal is to see even more conceptual documentation
  included with packages and frameworks.
• Add rich tutorials for new users. Tutorials can help elevate the Swift
  ecosystem of third-party packages by making it easy to create friendly
  learning experiences, which are especially great for developers new to the
  API. Like articles, tutorials can be easily included in the main documentation
  workflow
• Make it easy to connect documentation together. It’s easier to find
  documentation when it’s well organized. Another key goal is to provide an
  intuitive way for developers to organize documentation into logical groups and
  to write links to other pages.

Overview

Swift-DocC encompasses tools and libraries to help developers write and
generate documentation on many platforms, including macOS and Linux, with the
goal to support all platforms with a Swift toolchain. The docc command line
tool is already integrated in Xcode 13 and is architected in a way that
can be integrated with other build systems such as SwiftPM. The open source
project is composed of several components, some of which may be interesting in
their own right for building other developer tools. The components include:

• Swift-DocC — the documentation compiler tool that processes source file
  comments, standalone Markdown files, and related assets to produce a
  machine-readable JSON archive.
• Swift-DocC-Render — a JavaScript-based web application that renders
  compiled DocC archives.
• Swift-Markdown — a library that makes it easy to parse Markdown syntax in
  Swift.
• SymbolKit — a Swift library that parses the symbol graph files emitted by
  the Swift compiler. These files encapsulate information about a module’s APIs,
  including their documentation comments.

The tooling understands the Swift documentation comment syntax already popular
within the Swift community in stand-out tools like
Jazzy and
SwiftDoc, and in IDEs like Xcode.
It adds some novel syntax features, too. For example, the double-backtick
``SymbolName`` syntax creates links between symbols. An example:

Source file documentation comment

/// A model representing a sloth.
/// 
/// You can create a sloth using the ``init(name:color:power:)`` initializer, or
/// create a randomly generated sloth using a ``SlothGenerator``:
///
/// ```swift
/// let slothGenerator = MySlothGenerator(seed: randomSeed())
/// let habitat = Habitat(isHumid: false, isWarm: true)
/// do {
///     let sloth = try slothGenerator.generateSloth(in: habitat)
/// } catch {
///     fatalError(String(describing: error))
/// }
/// ```
public struct Sloth { … }

Rendered website

What’s Next?

Integration with Swift Tools

Building documentation should be as easy as building code. To that end, among
the next steps will be to include Swift-DocC with the core Swift tools, so all
Swift developers can easily document their code from the very beginning of a
project.

Like other components of the core Swift tooling, this project will follow the
Swift Evolution process, with one of the first tasks being to design the
integration with Swift Package Manager using extensible plug-ins. And soon,
Swift development trunk snapshots (for a release after Swift 5.5) will include
the Swift-DocC tools.

To read more about the future of Swift-DocC, check out the Swift-DocC project
announcement post in the
forums.

Adoption

Work is in progress to host generated documentation for the Swift-DocC project itself at
swift.org/documentation. Longer-term goals
include adding documentation to more packages, as well as migrating
documentation for the standard library and other documentation across
Swift.org. This will make it even easier for the community to participate in
documenting and teaching Swift.

Get Involved

Your experience, feedback, and contributions are greatly encouraged!

Questions?

Please feel free to post questions about this post on the associated
thread on the Swift
forums.