Skip to content

Documentation releases

The manual uses mike to publish several versions to the gh-pages branch. GitHub Pages must be configured once to deploy from that branch at /.

Automated channels

  • A pull request or push to main runs mkdocs build --strict; pull requests retain the rendered site/ as a seven-day preview artifact.
  • A push to main deploys the nightly manual.
  • A manual Deploy versioned documentation run publishes a numbered release and can move the stable alias/default.

The deployment job uses the exact versions in requirements.txt and the full Git history needed by the revision-date plugin.

Publish a release

Before moving stable:

  1. Check out the manual content that matches the application release.
  2. Update all explicit version facts, install commands, counts, examples, validation status, compatibility notes, the CPU/GPU operation matrix, and the distinction between installable and publicly admitted environments.
  3. Replace screenshots with captures from the same release.
  4. Re-run the documented installation check on each platform whose status will be labelled verified; state other platforms as pending.
  5. Confirm the release-candidate application commit, full CI/test counts, package/Twine/clean-wheel results, real-device evidence boundary, and final wheel/sdist hashes. Do not copy timing from a development report as a portable performance promise.
  6. Run mkdocs build --strict and visually review key pages, navigation, internal links, tables, and both themes.
  7. After the application tag is public, deploy the numbered manual with make_stable=false and verify it before the irreversible package upload.
  8. Publish and verify the matching application packages and GitHub prerelease.
  9. Run Deploy versioned documentation again for 0.13.0a6 with make_stable=true so the already-reviewed snapshot becomes the default.
  10. Open the public site, select both the numbered release and stable, then verify installation, search, code highlighting, redirects, and images.

The workflow executes the equivalent of:

mike deploy --push 0.13.0a6
mike deploy --push --update-aliases 0.13.0a6 stable
mike set-default --push stable

Never overwrite an old numbered manual with content for a different software release. Correct a serious documentation error with a transparent follow-up and record it in the repository history.

Preview versioned output locally

mike deploy 0.13.0a6 stable
mike deploy nightly
mike serve

Do not push the generated site/ directory; mike manages versioned content in the deployment branch.