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
External Documentation Links
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 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
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 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 |
|---|---|
|
|
Path to the Swift compiler |
|
|
Xcode developer directory (macOS) |