Version our documentation

[bendk]

[below is from @mhammond who took over the description to track the current status]

Now that #2077 is in-place I had a bit of a look at mike - it's conceptually a fairly simple tool - it manages a small amount of metadata about versions in a JSON file in the root of gh-pages, and it wraps the mkDocs build and publish flows to only updates a single directory of docs rather than the entire site. A subtle side-effect of this is that mike and the entire docs flow can never recreate the entire site, but instead needs to do updates of the existing gh-pages branch.

Another side-effect of this is that it can't really use the gh-pages/deploy action - we will need to deploy the old-school way executing mike deploy manually.

So my current plan is something like:

• Update our existing docs deploy flow to use mkDocs deploy in preparation for switching to mike.
• Update the mkDocs templates to include mike versioning (but this doesn't actually get rendered until versions are discovered at runtime via that json file in the root mentioned above)
• Manually edit the root of the docs site so it has the same redirecting index.html as jj
• In a throw-away branch, back-port Move doc generation to mkdocs. #2077 and a couple of other tweaks to the 0.27 branch and generate docs for 0.27.
• Manually mike deploy 0.27 mkDocs generated docs into a directory names 0.27 with an alias of latest (an alias is just a mike-managed symlink)
• Write a little Python script to replace all existing *.html files on the site to be a sym-link to a document of the same name in ./current

At this stage we should have a functioning site - albeit with only 1 version enabled. All previously existing .html pages should redirect to "current", which itself is currently symlink to 0.27

Then:

• Manually mike deploy the current main docs to a version called unreleased
• Update current CI actions to also mike deploy the current main docs to a version called unreleased
• Remove all old js, assets, etc.
• Document the new version release process to include the docs (part of which will be to use mike to point current to the new version)
• Work on automatically deploying new versions on new releases so that no extra manual steps are required when cutting new versions.

At this stage we should have a function site with 2 versions available to select from, 0.27 and unreleased, with latest being a symlink to 0.27
After the next major release we will have 3 versions - 0.27, 0.28 and unreleased, which latest being a symlink to 0.28.

Thoughts welcome!

[mhammond]

I had a look at jj as an example of a Rust project with great docs. They use the Python-based mkDocs whereas we use the Rust-based mdbook.
They then leverage the 'mike' tool to deploy and the mkDocs templating system does magic.

mkDocs uses jinja, which our templating engine askama is based on :)

I failed to find any mdbook themes or sites which had an easy version selector in the content.
crates.io has a version selector but I've no idea how that works. Anyone have any leads?

mkDocs looks very vibrant and functional - should we look into moving to it?

[badboy]

I failed to find any mdbook themes or sites which had an easy version selector in the content. crates.io has a version selector but I've no idea how that works. Anyone have any leads?

Do you mean docs.rs? That part is completely self-built, on top of the regular rustdoc output.

For mdbook there's nothing ready-to-use that I know of.
https://google.github.io/comprehensive-rust/ has a language switcher, using https://github.com/google/mdbook-i18n-helpers.
That I guess could be used as a basis for a version switcher.
But then we still need to build tooling to deploy all those versions.
And I bet no one here necessarily wants to maintain all that tooling.

mkDocs looks very vibrant and functional - should we look into moving to it?

Over in Data we use mkdocs in some places as well, e.g. https://mozilla.github.io/bigquery-etl/.
While I do like mdbook a lot, it is limited and not easy to extend, so chosing something else that already has that support might be worthwhile.

[mhammond]

I edited the description with my vague plan to move forward here.

[mhammond]

https://mozilla.github.io/uniffi-rs is now versioned 🎉