Skip Navigation
ArticleArticle

Plugin Options

Configure documentation generation with command-line options.

Overview

The Static Documentation Plugin accepts various options to customise the documentation generation process. All options are passed after the generate-static-documentation command.

Available Options

Output Directory

Specify where to generate documentation:

swift package generate-static-documentation --output ./docs

Default: .build/documentation

Target Selection

Document specific targets only:

swift package generate-static-documentation --target MyLib

Multiple targets:

swift package generate-static-documentation --target MyLib --target HelperLib

Dependency Handling

Include all dependencies in the documentation:

swift package generate-static-documentation --include-all-dependencies

Include specific dependencies:

swift package generate-static-documentation --include-dependency SomePackage

Exclude specific dependencies:

swift package generate-static-documentation --exclude-dependency LargePackage

Link to external documentation for modules or packages you’re not documenting locally:

swift package generate-static-documentation \
    --external-docs MyDependency=https://example.com/mydependency

The name before = is a module name or the name of a package dependency, which covers all of its modules; the URL is the root of the hosted documentation, without /documentation. Symbols of other modules that are not documented locally are shown as unlinked text.

Search Functionality

Disable client-side search (reduces output size):

swift package generate-static-documentation --disable-search

Theme

Choose a built-in theme by name (default, docc-static-classic or its alias classic), or pass a theme-settings.json file or a theme directory:

swift package generate-static-documentation --theme classic
swift package generate-static-documentation --theme ./MyTheme

Add a stylesheet on top of the theme, or leave out dark mode styles:

swift package generate-static-documentation --custom-css ./tweaks.css
swift package generate-static-documentation --disable-dark-mode

Add a custom footer to all pages:

swift package generate-static-documentation --footer "<p>Copyright 2024 My Company</p>"

Verbose Output

Show detailled progress information:

swift package generate-static-documentation --verbose

Common Combinations

Fast Development Build

Minimal build for quick iteration:

swift package --scratch-path /tmp/build \
    generate-static-documentation \
    --target MyLib \
    --disable-search

Production Build

Full documentation with all options:

swift package generate-static-documentation \
    --output ./docs \
    --include-all-dependencies \
    --exclude-dependency TestSupport \
    --footer "<p>Built with swift-docc-static</p>" \
    --verbose

Documentation for Publishing

Ready for hosting:

swift package generate-static-documentation \
    --output ./public \
    --external-docs MyDependency=https://example.com/mydependency

Using with swift package Options

The plugin respects standard swift package options. Specify them before the plugin command:

# Use a specific scratch path
swift package --scratch-path /tmp/build generate-static-documentation

# Use a specific configuration
swift package -c release generate-static-documentation

# Specify package location
swift package --package-path /path/to/package generate-static-documentation

Environment Variables

The plugin respects standard Swift environment variables:

Variable

Description

SWIFT_EXEC

Path to the Swift compiler

DEVELOPER_DIR

Xcode developer directory (macOS)

See Also