# Swift-DocC for Swift Package Documentation

> Swift-DocC compiles source comments, tutorials, and long-form articles into rendered documentation for Swift frameworks and packages. It is a strong fit for Swift projects already using SwiftPM or Xcode, but the separately versioned library does not promise source stability.

**swiftlang/swift-docc** — Documentation compiler that produces rich API reference documentation and interactive tutorials for your Swift framework or package.

- Repository: https://github.com/swiftlang/swift-docc
- Website: https://swift.org/documentation/docc
- Stars: 1,370 · Forks: 186
- Language: Swift
- License: Apache-2.0
- Published: 2026-10-16 · Updated: 2026-10-16 · Language: en
- Canonical page: https://hysenlabs.com/projects/swiftlang-swift-docc

## What Swift-DocC Solves for Swift Package Authors

Swift-DocC is a documentation compiler aimed specifically at Swift frameworks and packages. It addresses two related publishing needs that are easy to treat as separate: maintaining API reference material derived from a codebase and producing interactive tutorials that explain how to use that code. The project documentation also covers long-form content, so a documentation set can include explanatory articles rather than only symbol listings.

The intended users are maintainers who already work in the Swift ecosystem. The README recommends the Swift-DocC Plugin when documenting a package through SwiftPM. Xcode is another documented route for apps, frameworks, and packages. On macOS, the standalone CLI is available through `xcrun docc`, while installations that include the Swift toolchain expose `docc` on both macOS and Linux.

This positioning is narrower than a general site generator. The repository does not describe Swift-DocC as a framework for rendering an arbitrary website or maintaining a general knowledge base. Its documented output is developer documentation, with API reference documentation, tutorials, and formatted prose. The homepage at `https://swift.org/documentation/docc` is the entry point for the full user documentation, while the repository focuses on the compiler, CLI, SwiftDocC library, tests, and build infrastructure.

Swift-DocC is therefore most relevant when source comments and package structure need to become a coherent documentation product. It is less clearly suited to teams whose documentation lives primarily in a wiki, another static site generator, or an unrelated documentation platform.

## How DocC Processes Swift Documentation

The `docc` command is the command line interface for Swift-DocC. According to the README, it supports generating and previewing documentation. The repository also exposes the `SwiftDocC` library as a separately versioned component, but the public starting points in the README focus on invoking DocC through SwiftPM's plugin, `xcrun docc`, Xcode, or the toolchain-provided CLI.

The documentation system is tied to a Swift project rather than being an isolated text converter. Formatting guidance is provided for symbols, tutorials, and article-style content, which indicates that the compiler organizes several content forms into one rendered documentation experience. The API reference can be derived from documented Swift symbols, while tutorials provide a task-oriented path through an SDK or framework. The README does not expose the internal compiler stages or a complete input-to-output pipeline, so those details should not be inferred beyond the documented sources and outputs.

Previewing is part of the workflow rather than an afterthought. The Swift-DocC Plugin documentation has separate instructions for previewing documentation, generating it for a specific target, and publishing it to a website or GitHub Pages. This separation matters because local review and hosting solve different problems. A local preview helps authors inspect rendering, while publication requires a destination and a deployment process.

The architecture is best understood as a compiler embedded in several Swift workflows. SwiftPM supplies package-aware integration, Xcode supplies project integration, and the toolchain supplies the command. The CLI itself follows the Swift compiler's versioning scheme, so its availability is tied to the installed Swift toolchain.

## Installing and Running DocC Through the Swift Toolchain

The repository does not give a standalone package installation command for users who already have Swift. Instead, it says that Swift-DocC is included in the Swift toolchain for macOS and Linux. On macOS with Xcode installed, the recommended standalone invocation is `xcrun docc`. The same CLI can be inspected with the documented help command.

Use this command to inspect the CLI options available in the installed toolchain:

```bash
docc --help
```

The output should list the command line interface's supported help information. The README does not specify a particular diagnostic message or a sample output, so the exact result depends on the installed toolchain.

For a first real documentation operation, the README points package authors to the Swift-DocC Plugin. The plugin documentation covers generating documentation for a specific SwiftPM target and previewing the result. That plugin is the documented path for a package, while `xcrun docc` is the documented direct CLI path when Xcode is present. The repository does not provide enough command syntax to reproduce a complete generation invocation in this article, so adding flags would risk documenting an unsupported command.

The project also includes a Docker development environment. Its `Dockerfile` starts from `swift:6.3-noble`, creates a `build-user`, and sets the working directory to `/home/build-user`. That file is aimed at building or developing the project in a container, not at installing DocC for application users.

For package documentation, the practical first sequence is therefore: install the relevant Swift toolchain, use `docc --help` to confirm CLI availability, and then follow the Swift-DocC Plugin documentation for target generation and preview. This sequence avoids pretending that the CLI and plugin expose identical workflows.

## Choosing the SwiftPM Plugin, Xcode, or `xcrun`

Swift-DocC offers several entry points, and choosing the wrong one can add setup friction. SwiftPM users are directed to the Swift-DocC Plugin, which is designed around package targets and includes documentation for generating and previewing output. This is the clearest documented choice when the documentation belongs to a Swift package.

Xcode is the documented route for apps, frameworks, and packages. The README links to Apple's Xcode documentation for writing documentation rather than duplicating Xcode project settings here. That distinction is useful because Xcode can supply its own project context, build configuration, and integration conventions that are not described in this repository.

For standalone use, the README specifically recommends `xcrun docc` when Xcode is installed. `xcrun` locates the appropriate tool through Xcode rather than requiring the author to construct a direct executable path. The Swift toolchain also includes Swift-DocC on Linux, although the README does not claim that `xcrun` is available there. Linux users should therefore treat the toolchain-provided `docc` command as the relevant documented CLI path unless their own environment provides another integration.

The three routes are not interchangeable documentation formats. The README points to separate instructions for package generation, previewing, website hosting, GitHub Pages, and Xcode documentation. A project should first decide whether its primary output is a Swift package page, an Xcode project artifact, or a hosted documentation archive, then follow the matching guide.

## Versioning, Maintenance, and Upgrade Boundaries

The repository is not archived, and its recorded last push was on 2026-10-15. The README describes Swift-DocC as actively developed. Recent release entries include `swift-6.4.0-RELEASE`, `swift-6.3.2-RELEASE`, and `swift-6.3.1-RELEASE`, which places the repository's recent release work around Swift 6.3 and Swift 6.4.

The important upgrade boundary is explicit. The `docc` CLI is integrated into the Swift toolchain and follows the Swift compiler's versioning scheme. The `SwiftDocC` library is versioned separately, and the README says its source stability is not guaranteed. Teams should not assume that updating the toolchain, updating the plugin, and updating the library are interchangeable operations.

That distinction affects maintenance planning. A project that invokes the CLI through a toolchain or Xcode may primarily manage toolchain upgrades. A project that imports `SwiftDocC` directly must account for separate library versioning and possible source changes. The README does not provide a compatibility matrix or a migration policy for library consumers, so that check belongs in a project's own dependency review.

The project is licensed under Apache-2.0, with the repository's `NOTICE.txt` and license files providing the project licensing context. The `Dockerfile` header identifies Apache License v2.0 with Runtime Library Exception. That is a licensing fact, not legal advice. Teams should review the repository license files and dependency terms for their distribution requirements rather than infer obligations from the compiler name.

## What Swift-DocC Does Not Solve

The clearest limitation is source stability for the `SwiftDocC` library. The CLI's relationship to the Swift toolchain does not guarantee that direct library consumers have stable source APIs. That makes Swift-DocC a weaker fit for a product that intends to build its own compiler extensions around the library unless the team is prepared to absorb API changes.

The README also leaves several operational details to external documentation. It does not specify a universal deployment command for GitHub Pages, a complete list of supported Swift versions, or a repository-contained command for generating every package target. The linked plugin and distribution guides are necessary for those decisions. A team should not assume that successful local previewing automatically solves hosting, authentication, or documentation versioning.

A different class of project may choose a conventional documentation tool instead. A team with prose-heavy content and no need for Swift symbol reference or interactive tutorials may find a general Markdown site workflow more direct. Conversely, a team that needs generated API pages, symbol links, tutorials, and Swift-specific formatting has a clearer reason to use Swift-DocC. The trade-off is ecosystem fit rather than a claim that one documentation format is universally better.

## Conclusion

Swift package and framework maintainers that already publish through SwiftPM or Xcode should evaluate Swift-DocC first, especially when they need generated API references alongside tutorials. Projects requiring a stable source-level SwiftDocC library should not adopt the library API without accounting for its separate versioning and lack of source-stability guarantees. Before committing, verify the documentation route used by the target audience, the Swift toolchain available on each build platform, and the deployment requirements described in the project's distribution documentation.

## FAQ

### What is Swift-DocC used for?

Swift-DocC is a documentation compiler for Swift frameworks and packages. It supports generated API reference documentation, interactive tutorials, and long-form documentation content.

### How do I run DocC from the command line?

The README says Swift-DocC is included in the Swift toolchain on macOS and Linux. With Xcode installed, use `xcrun docc`; `docc --help` displays the CLI help.

### Is the SwiftDocC library source-stable?

No source-stability guarantee is documented for the separately versioned `SwiftDocC` library. The `docc` CLI instead follows the Swift compiler's versioning scheme.

### Can Swift-DocC publish documentation to GitHub Pages?

The README links to the Swift-DocC Plugin documentation for publishing documentation to a website or GitHub Pages. It does not provide the publishing command in the repository README itself.

## Sources

- [License: Apache-2.0](https://github.com/swiftlang/swift-docc/blob/main/LICENSE)
- [Project website](https://swift.org/documentation/docc)
- [README](https://github.com/swiftlang/swift-docc/blob/main/README.md)
- [Releases](https://github.com/swiftlang/swift-docc/releases)
- [swiftlang/swift-docc on GitHub](https://github.com/swiftlang/swift-docc)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/swiftlang-swift-docc