Swift 5.6 released with Xcode 13.3 implements evolution proposals extensible built tools (SE-0303) and its extension command plugins (SE-0332). This opens up plugins for Swift packages. Along with that, Apple released DocC command plugin for Swift packages, which supports generating static webpages containing the documentation of the package.
Swift-DocC plugin
Apple’s Swift-DocC plugin comes with pretty rich documentation which covers many aspects of the documentation generation process. Something to keep in mind still is that the generated website can’t just be opened with Safari like we might have been used to when using Jazzy. The plugin has a separate preview command if we want to open the documentation locally. That command starts a local web server which renders the site.
Getting started with Swift-DocC plugin
As an example, we’ll take my IndexedDataStore Swift package and see what are the steps to generate and preview the documentation. But before that, for local usage, I would like to highlight the fact that Xcode’s Product menu contains a “Build Documentation” command which generates documentation and adds it to the Developer Documentation window.
OK, back to generating HTML webpages ourselves. The very first thing we need to do is adding the docc plugin as a dependency to our Swift package. If we have done that, then we have access to new commands which the plugin defines.
dependencies: [
.package(url: "https://github.com/apple/swift-docc-plugin", from: "1.0.0"),
],
Let’s take a look at the preview command at first which generates documentation, spins up a local web server which renders it.
swift package --disable-sandbox preview-documentation --target IndexedDataStore
Building for debugging...
Build complete! (0.13s)
Template: /Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/share/docc/render
========================================
Starting Local Preview Server
Address: http://localhost:8000/documentation/indexeddatastore
========================================
The other command is the one which generates the static documentation webpage, which we can then commit to GitHub and let the GitHub pages to render.
swift package \
--allow-writing-to-directory ./docs \
generate-documentation \
--target IndexedDataStore \
--disable-indexing \
--output-path ./docs \
--transform-for-static-hosting \
--hosting-base-path IndexedDataStore
Since plugin commands run under a sandboxed environment, we’ll need to explicitly define which folder is writable with the --allow-writing-to-directory argument. The --disable-indexing argument disables generating index, which is used by Xcode or other IDEs. The --transform-for-static-hosting removes the need to have any routing rules on the web server. And finally, --hosting-base-path defines the base-path of the documentation. Meaning, if the GitHub repository name is IndexedDataStore then we should pass in IndexedDataStore. Otherwise, relative links in the generated webpage are incorrect. The full format of the URL when it is pushed to a branch and GitHub pages is configured to read from the pushed branch with relative path set to /docs is: https://<username>.github.io/<repository-name>/documentation/<target-name> .
For IndexedDataStore, it is https://laevandus.github.io/IndexedDataStore/documentation/indexeddatastore/. Note that the target name is in lowercase. The link won’t work since I switched GitHub pages back to the Jazzy documentation, which is auto-generated on merge.
If this was helpful, please let me know on Mastodon@toomasvahter or Twitter @toomasvahter. Feel free to subscribe to RSS feed. Thank you for reading.
Augmented Code 