The Swift-DocC plugin is a Swift Package Manager command plugin that supports building documentation for SwiftPM libraries and executables.
Please see the plugin's documentation for more detailed usage instructions.
To use the Swift-DocC plugin with your package, first add it as a dependency:
let package = Package(
// name, platforms, products, etc.
dependencies: [
// other dependencies
.package(url: "https://github.com/apple/swift-docc-plugin", from: "1.1.0"),
],
targets: [
// targets
]
)Swift 5.6 is required in order to run the plugin.
You can then invoke the plugin from the root of your repository like so:
swift package generate-documentationThis will generate documentation for all compatible targets defined in your package and its dependencies and print the location of the resulting DocC archives.
If you'd like to generate documentation for a specific target and output that to a specific directory, you can do something like the following:
swift package --allow-writing-to-directory ./docs \
generate-documentation --target MyFramework --output-path ./docsNotice that the output path must also be passed to SwiftPM via the
--allow-writing-to-directory option. Otherwise SwiftPM will throw an error
as it's a sandbox violation for a plugin to write to a package directory without explicit
permission.
Any flag passed after the generate-documentation plugin invocation is passed
along to the docc command-line tool. For example, to take advantage of Swift-DocC's new support
for hosting in static environments like GitHub Pages, you could run the following:
swift package --allow-writing-to-directory ./docs \
generate-documentation --target MyFramework --output-path ./docs \
--transform-for-static-hosting --hosting-base-path MyFrameworkThe Swift-DocC plugin also supports previewing documentation with a local web server. However, unlike converting documentation, previewing is limited to a single target a time.
To preview documentation for the MyFramework target, you could run the following:
swift package --disable-sandbox preview-documentation --target MyFrameworkTo preview documentation for a product defined by one of your package's dependencies, you could run the following:
swift package --disable-sandbox preview-documentation --product OtherFrameworkFor details on how to best build documentation for hosting online and a specific tutorial for publishing to GitHub Pages, please see the plugin's documentation.
The Swift-DocC plugin tracks all bug reports with GitHub Issues. When you submit a bug report we ask that you follow the provided template and provide as many details as possible.
If you can confirm that the bug occurs when using the latest commit of the Swift-DocC plugin
from the main branch, that will help us track down the bug faster.
For feature requests, please feel free to file a GitHub issue or start a discussion on the Swift Forums.
Don't hesitate to submit a feature request if you see a way the Swift-DocC plugin can be improved to better meet your needs.
All user-facing features must be discussed in the Swift Forums before being enabled by default.
Please see the contributing guide for more information.