DocC plugin PSA

In my last two posts about using DocC, I’ve been implicitly encouraging the use of the new docc-plugin for the Swift package manager. I did so knowing that it is in beta and the underlying APIs are evolving – and in my example scripts I include how to do the same thing with commands that directly invoke the swift compiler and DocC to generate documentation.

With the release of Xcode 13.3 beta 3 today, the API for package manager command plugins (of which the swift-docc-plugin is a lovely example) has changed slightly – and as such, what’s currently on the main branch isn’t compatible. There’s a pending pull request which I believe will resolve and update things back to working, but if you’re using the plugin, you should be aware that there’s an issue.

UPDATE

The pull request was merged on March 1st, which resolves using the plugin with Xcode 13.3 beta 3, and Ethan posted a bit of nice detail on the Swift Forums showing what’s changed when you use the plugin after the Swift Package Manager API updates. The big piece is that the --target option moved from in front of generate-documentation to after it, and there’s additional options for specifying a specific product, useful if you have a swift package that generates multiple products.

In the meantime, using docc on the command line directly does the job well, and hopefully soon we will have a fix added to the plugin for the updated API. I also hope that a release will be available before too long, but that will only happen when all the moving parts have stabilized. It is a lovely tool, and we’re in a beta period – so I’m not surprised that there are a few bumps along the road. I’m sure the end result will be better for the iteration.

In case you need the earlier steps laid out, here’s a script for generating documentation into a directory for static hosting:

#!/bin/bash

set -e  # exit on a non-zero return code from a command
set -x  # print a trace of commands as they execute

rm -rf .build
mkdir -p .build/symbol-graphs

$(xcrun --find swift) build --target RSTree \
    -Xswiftc -emit-symbol-graph \
    -Xswiftc -emit-symbol-graph-dir -Xswiftc .build/symbol-graphs

# Enables deterministic output
# - useful when you're committing the results to host on github pages
export DOCC_JSON_PRETTYPRINT=YES

$(xcrun --find docc) convert Sources/RSTree/Documentation.docc \
    --output-path ./docs \
    --fallback-display-name RSTree \
    --fallback-bundle-identifier com.github.heckj.RSTree \
    --fallback-bundle-version 0.1.0 \
    --additional-symbol-graph-dir .build/symbol-graphs \
    --emit-digest \
    --transform-for-static-hosting \
    --hosting-base-path 'RSTree'