Publishing the Documentation

These docs are published on Read the Docs, which builds them straight from the repository. Every push to an activated branch, and every new release tag, triggers a build of that version; readers switch between versions with the version flyout that Read the Docs injects into every page.

Versions

Read the Docs treats each git branch or tag as a separate version with its own URL under https://tabascal.readthedocs.io/en/<version>/.

Version

Built from

Purpose

stable

the highest vX.Y.Z tag

The default version — what visitors get from the bare project URL.

latest

the main branch

The current development docs, ahead of any release.

vX.Y.Z

that release tag

Frozen docs for a published version.

other branches

that branch

Long-lived work that needs its own published docs.

Two consequences worth knowing:

  • A version is only buildable if .readthedocs.yaml exists on it. Branches and tags created before that file was added cannot be built, so the first release tag to appear as a version must be cut after it landed on main.

  • stable only exists once there is a release tag. Until the first vX.Y.Z tag is pushed, the default version has to be latest; see the setup checklist below.

The version shown in the sidebar comes from the installed package metadata (pyproject.toml’s version). Branch builds append the branch name to it — 0.0.1 (latest) — since that version number is the release being worked towards rather than one that has been published.

Publishing a release version

  1. Set version in pyproject.toml to the new release number and merge it.

  2. Tag the merge commit vX.Y.Z and push the tag.

  3. Activate the new version in the Read the Docs admin (Versions), unless an automation rule already activates tags. stable follows the highest tag automatically once it is active.

Publishing another branch

Activate it under Versions in the project admin. The branch needs .readthedocs.yaml in it — rebase it onto main first if it predates this setup. Deactivating a version hides it from the flyout again; nothing in the repository needs to change either way.

One-time project setup

Only needed until the project exists on Read the Docs:

  1. Sign in to https://readthedocs.org with the GitHub account that can administer epfl-radio-astro/tabascal and import the repository. The project slug decides the domain, so pick tabascal if it is free.

  2. Under Admin → Settings, set the default version to latest (the main branch) — stable does not exist until the first release tag — and set the default branch to main.

  3. Under Admin → Settings, enable Build pull requests for this project so documentation changes get a preview build on each pull request.

  4. Under Versions, activate main (published as latest) and any other branch that should be published.

  5. After the first vX.Y.Z tag is published, change the default version to stable so the bare project URL serves the latest release.

  6. Add the resulting URL to the repository description and to [project.urls] in pyproject.toml.

Building the docs locally

pixi run -e dev docs-build

Then open docs/_build/html/index.html. Read the Docs and the Docs GitHub workflow both build with warnings treated as errors, so it is worth reproducing that before pushing:

pixi run -e dev sphinx-build -b html -W --keep-going docs docs/_build/html