Plugin 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

External Documentation Links

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

swift package generate-static-documentation \
    --external-docs ArgumentParser=https://swiftpackageindex.com/apple/swift-argument-parser

Search Functionality

Disable client-side search (reduces output size):

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

Custom Footer

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 com.apple.documentation=https://developer.apple.com

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: