Swift-DocC sidebar

ethankusters · April 7, 2022, 10:04pm

I'm excited to announce that the Swift-DocC sidebar has been enabled by default in Swift-DocC-Render with:

The sidebar will only be available for DocC archives produced by the latest version of DocC that includes the necessary index file.

I've updated the ArgumentParser demo with the latest changes: https://ethan-kusters.github.io/swift-argument-parser/documentation/argumentparser/.

If you'd like to try out the sidebar with your own Swift Package, you can do the following:

Testing instructions:

Note that I'm going to use the Swift-DocC Plugin to simplify the instructions here but it's not actually required for this functionality. It just makes testing prerelease versions of the docc CLI a little more user-friendly.

Build the latest version of Swift-DocC:

git clone https://github.com/apple/swift-docc.git
cd swift-docc
swift build

Set the DOCC_EXEC environment variable to your locally built copy of docc:
```
export DOCC_EXEC=`pwd`/.build/debug/docc
```

Clone the latest pre-built version of Swift-DocC-Render:

git clone https://github.com/apple/swift-docc-render-artifact.git
cd swift-docc-render-artifact

Set the DOCC_HTML_DIR environment variable to your local copy of Swift-DocC-Render:
```
export DOCC_HTML_DIR=`pwd`/dist
```

Adopt the Swift-DocC-Plugin in your package by following the instructions here.
```
.package(url: "https://github.com/apple/swift-docc-plugin", from: "1.0.0"),
```

Change directory to your package and run the preview-documentation command for your target:

cd <path-to-your-package>
swift package --disable-sandbox preview-documentation --target <name-of-package-target>

That's it!

If you encounter any issues while trying things out, a bug report on bugs.swift.org (and soon GitHub Issues) would be really appreciated.

- Ethan