Swift-DocC Plugin
The Swift-DocC plugin is a Swift Package Manager command plugin that supports building documentation for SwiftPM libraries and executables.
Usage
Please see the plugin's documentation for more detailed usage instructions.
Adding the Swift-DocC Plugin as a Dependency
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.0.0"),
],
targets: [
// targets
]
)
Swift 5.6 is required in order to run the plugin.
Converting Documentation
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 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 MyFramework
Previewing Documentation
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
Hosting Documentation
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.
Submitting a Feature Request
For feature requests, please feel free to create an issue on Swift JIRA with the New Feature type 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.
Contributing to the Swift-DocC Plugin
Please see the contributing guide for more information.
2 May 11, 2022
2 Mar 25, 2022
1 Feb 18, 2022
10 Oct 30, 2022
16 Aug 10, 2022
1 Oct 23, 2021
0 Nov 4, 2021
1 May 10, 2022
22 Jan 4, 2023
0 Jan 8, 2022
9 Jan 14, 2021
20 Jan 3, 2022
29 Aug 18, 2018
38 Jun 3, 2021
77 Jul 1, 2022
83 Jan 3, 2023
322 Sep 7, 2022
242 Jul 20, 2022
477 Sep 23, 2022