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-documentation
This 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 ./docs
Notice 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
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 MyFramework
The 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 MyFramework
To 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 OtherFramework
For 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
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.
|Last commit: 4 weeks ago|
You can now generate documentation that includes Swift symbols that extend other modules when building with Swift 5.8 or later. This is an opt-in feature that can be used by passing the
swift package generate-documentation --include-extended-types --target [target-name]
You can now generate documentation that excludes compiler synthesized symbols provided by default implementations of protocol requirements. This is an opt-in, experimental feature that can used by passing the
swift package generate-documentation --experimental-skip-synthesized-symbols --target [target-name]
1.2.0 release includes contributions from @finestructure, @sofiaromorales, and @theMomax. Thank you!
Swiftpack is being maintained by Petr Pavlik | @ptrpavlik | @swiftpackco | API | Analytics