Supporting Swift 5.8 Docc feature - linking to GitHub repo sources

[heckj]

For some open source packages, there's a cool feature that was introduced and included in the Swift 5.8 release chain that supports the ability to render HTML documentation that includes links back to source files in the hosted git repository - with built-in support for GitHub, GitLab, and BitBucket. The core of it's embedded into DocC itself, so its release is bound to the overall toolchain release. Apple's documentation for it is included within Distributing Documentation to Other Developers, sourced from their repo.

To use it, it works with swift-docc-plugin without any changes or updates needed there - it ends up being additional command line options that are passed through transparently. I just did a proof of concept run of this while doing some documentation work for package-benchmark. /cc @hassila

To see what this looks like in action, I have a GitHub hosted repo of the package docs in my own fork. If you dig into the classes (such as Benchmark), you'll see an additional little Swift image and a link to the source:

It applies the same for methods, initializers, properties, etc.

To enable this, there were three additional CLI options that I passed into swift package generate-documentation:

--source-service github \
--source-service-base-url https://github.com/ordo-one/package-benchmark/blob/main \
--checkout-path ${ROOT_DIR}

The first one is simply which git hosting provider is being used, and since you have the repository already, it's a pretty straightforward heuristic to snag that out. The second is the base URL - and this is where I suspect enabling this feature in SPI might require an addition to .spi.yml - the last element in the URL is the branch or tag (or generally a committish) where the service has a publicly accessible URL for various files. Depending on how the underlying project is dealing with branch names, release branches, and their tagging patterns, this could all be a bit tricky to infer. The key on this one is main, the rest is pretty easy to put together heuristically - org/account, and repo I suspect are already known.

The last option bit me the first time I tried it - it's an absolute path to where you have the repository cloned when you're running the generate-documentation command. It doesn't accept a relative path (enhancement req issued on swift-docc) - there's a thread in the Swift forums with some of the detail. Long and short though is the absolute path would be specific to your runners/builders, and couldn't be easily specified externally (as far as I know).

Anyway, that's the whole detail. If the whole generate-documentation command I'm using would be useful, here's a sample (including a bit I copied from update-gh-pages-documentation-site in swift-markdown for determining the absolute path within a shell script:

#!/bin/bash

set -e

# borrowed filepath from
# https://github.com/apple/swift-markdown/blob/main/bin/update-gh-pages-documentation-site

filepath() {
    [[ $1 = /* ]] && echo "$1" || echo "$PWD/${1#./}"
}

ROOT_DIR="$(dirname $(filepath $0))"
#echo "filepath is $(filepath $0)"
#echo "ROOT_DIR is ${ROOT_DIR}"

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

# Swift docc plugin for hosted content
$(xcrun --find swift) package \
    --allow-writing-to-directory ./docs \
    generate-documentation \
    --fallback-bundle-identifier com.github.ordo-one.package-benchmark \
    --target Benchmark \
    --output-path ./docs \
    --emit-digest \
    --disable-indexing \
    --transform-for-static-hosting \
    --hosting-base-path 'package-benchmark' \
    --source-service github \
    --source-service-base-url https://github.com/ordo-one/package-benchmark/blob/main \
    --checkout-path ${ROOT_DIR}

[finestructure]

We have the clone url and the git reference available at the point of doc generation:

So unless I'm missing something we should easily be able to create the service base url

    --source-service-base-url \(cloneURL.droppingGitExtension())/blob/\(reference)

[daveverwer]

This would be great to support when we roll out 5.8 👍 Also, just as a note to myself, we should highlight this in a 5.8 blog post. Lots of good DocC stuff like quick access, too.