[2/x] Migrate to DocC for API reference docs #257
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This was referenced Jan 7, 2022
Base automatically changed from
dev/andrewchang-bird/cleanup-release-automation
to
master
January 7, 2022 23:04
Requires running DocC from mainline
andrewchang-bird
force-pushed
the
dev/andrewchang-bird/docc
branch
from
0694871
to
144299b
Compare
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Stack:
📚 #259 [4/x] Bump versions to 0.19.0
📚 #258 [3/x] Codemod Xcode-generated file header comments
📚 #257 ← [2/x] Migrate to DocC for API reference docs
📚 #256 [1/x] Clean up automation pipeline
Overview
We currently use Swift Doc to generate the API reference documentation site, which was deprecated after Apple announced their fancy documentation generator at WWDC 2021 called DocC. In addition to producing great looking content pages, DocC supports arbitrary markdown-formatted articles, interactive tutorials, and works well with SwiftPM packages.
DocC’s feature set makes it easy to consolidate our existing documentation, which is scattered across the README, GitHub wiki, and API reference site. There are several benefits as well, including searchability (Google doesn’t index GitHub wiki pages) and the ability to decouple the README contents from releases.
Path Rewriting
The goal is to host the documentation site on a dedicated vanity domain for searchability and memorability. Unfortunately, DocC doesn’t support serving documentation from the root of the site and instead expects
/documentation/mockingbirdfor articles and/tutorials/mockingbirdfor tutorials. Since we’ll only ever show documentation for Mockingbird on the site, it doesn’t make sense to include “mockingbird” in the path.The mainline versions of Swift-DocC and Swift-DocC-Render support generating a documentation archive with a custom base path for static hosting compatibility, but this is strictly additive, e.g.
/foo/bar/documentation/mockingbird(see: swiftlang/swift-docc-render#24, swiftlang/swift-docc#44).To get the desired page paths, I’ve modified the renderer to rewrite URLs in the JSON data to the root. Currently the rewrites are hardcoded to minimize the number of changes since they are applied as a series of patches.
Syntax Highlighting
Swift-DocC-Renderer uses a lightly customized version of highlight.js for syntax highlighting code blocks which differs a bit from GitHub. I’ve patched the highlighting to make the Mockingbird testing API more readable and fix some minor issues (SR-15681).
Test Plan
Documentation archives are built as part of the release GitHub workflow and pulled by the documentation site here: https://mockingbirdswift.com/