docc-static
A command-line tool for generating static HTML/CSS documentation from Swift packages.
Overview
The docc-static command-line tool generates pure HTML/CSS documentation from Swift packages. The output works locally as file:// URLs and can be hosted on any static web server without requiring JavaScript (on the server or in the browser) for basic navigation.
For programmatic access, see the DocCStatic library. For an integrated SPM workflow, use the GenerateStaticDocumentation plugin.
Installation
Install using Homebrew:
brew tap mipalgu/tap
brew install swift-docc-static
Or build from source:
git clone https://github.com/mipalgu/swift-docc-static.git
cd swift-docc-static
swift build -c release
Quick Start
Generate documentation for a Swift package:
docc-static generate --package-path /path/to/package --output ./docs
Preview the generated documentation:
docc-static preview --output ./docs
Commands
generate
Generate documentation from a Swift package:
docc-static generate [options]
Options:
|
Option |
Description |
|---|---|
|
|
Path to the Swift package (default: |
|
|
Output directory (default: |
|
|
Scratch path for Swift build operations |
|
|
Pre-generated symbol graph directory |
|
|
Specific targets to document (repeatable) |
|
|
Include all dependencies |
|
|
Include specific dependency (repeatable) |
|
|
Exclude specific dependency (repeatable) |
|
|
Docs base URL of a module or package ( |
|
|
Archive to resolve external links against |
|
|
Disable client-side search |
|
|
Custom HTML for page footer |
|
|
Built-in theme, theme settings file or directory |
|
|
CSS file applied after the theme’s stylesheets |
|
|
Leave out dark mode styles |
|
|
Enable verbose output |
|
|
Show summary statistics after generation |
Examples:
# Generate with verbose output
docc-static generate -v
# Document specific targets
docc-static generate -t MyLib -t MyOtherLib
# Include dependencies except specific ones
docc-static generate -I -x ExcludedPackage
# Link to the hosted documentation of a dependency
docc-static generate -e MyDependency=https://example.com/mydependency
-e Name=URL gives the base URL of documentation hosted elsewhere. Name is a module name, or the name or identity of a package, which covers all of its modules. Symbols of those modules that are not part of the generated documentation link to URL/documentation/<module>/<path>/; other symbols outside the generated documentation are shown as unlinked text. The same names are matched against the bundle identifiers of doc:// links in documentation text.
render
Render static HTML from an existing DocC archive:
docc-static render <archive-path> --output ./docs
The render and preview commands accept the theme options and the output options (--disable-search, --footer, --verbose, --summary) of generate.
preview
Start a local preview server:
docc-static preview --output ./docs --port 8080