Skip Navigation
FrameworkFramework

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

-p, --package-path

Path to the Swift package (default: .)

-o, --output

Output directory (default: .build/documentation)

--scratch-path

Scratch path for Swift build operations

-S, --symbol-graph-dir

Pre-generated symbol graph directory

-t, --target

Specific targets to document (repeatable)

-I, --include-all-dependencies

Include all dependencies

-i, --include-dependency

Include specific dependency (repeatable)

-x, --exclude-dependency

Exclude specific dependency (repeatable)

-e, --external-docs

Docs base URL of a module or package (Name=URL)

-d, --dependency

Archive to resolve external links against

-D, --disable-search

Disable client-side search

--footer

Custom HTML for page footer

--theme

Built-in theme, theme settings file or directory

--custom-css

CSS file applied after the theme’s stylesheets

--disable-dark-mode

Leave out dark mode styles

-v, --verbose

Enable verbose output

-s, --summary

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

Topics