Managing Multiple Documentation Versions with Read the Docs

When a library ships frequent releases, users often land on documentation that belongs to an older version, leading to confusion and broken links. Maintaining a separate copy of the docs for each release multiplies effort and makes it hard to keep everything in sync. Read the Docs (RTD) solves this by automatically building and serving a distinct version of the documentation for every Git tag or branch, exposing a version picker so readers can jump to the exact release they need.

Why versioned documentation matters

Without versioning, a single "latest" docs page must serve all audiences. Users of v1.2 may see API changes that only appear in v2.0, while newcomers miss out on stable guides tied to a specific release. RTD’s built‑in versioning eliminates this mismatch by:

• Watching the connected VCS (GitHub, GitLab, Bitbucket) for new tags or branches.
• Triggering a fresh documentation build for each detected ref.
• Storing the build under a URL path like /<version>/.
• Providing a dropdown selector in the site header that lets visitors switch between latest, stable, and any named version.

Setting up versioning in Read the Docs

First, ensure you have administrative access to the RTD project and push rights to the source repository. Then add a minimal configuration file that tells RTD how to treat your main branch and any tags you want to expose as readable versions.

Add .readthedocs.yaml

version: 2

build:
  os: ubuntu-22.04
  tools:
    python: "3.11"

# Treat the default branch as the "stable" version
versions:
  stable: main

# Optional: map tags to friendly names
aliases:
  # Example: a tag v1.2.3 appears as "1.2" in the picker
  "1.2": v1.2.3

Place this file at the repository root, commit, and push to the default branch (usually main). RTD will detect the file on the next build and apply the version settings.

Worked example: publishing a new release

Suppose you maintain a Python library and just tagged release v2.1.0. Follow these steps to make the version appear in RTD:

1. Create the tag locally (requires write access to the repo):

   git tag v2.1.0
   git push origin v2.1.0

2. Wait for RTD to notice the new tag. RTD polls the VCS; a build should start within a few minutes. You can monitor progress on the project’s Builds page.
3. Verify the build succeeded. Click the build log for the v2.1.0 version and look for a successful exit status.
4. Check the version picker. Visit your RTD site (e.g., https://myproject.readthedocs.io) and open the dropdown in the header. You should see entries like latest, stable, and 2.1 (the alias you defined). Selecting 2.1 loads the documentation built from the v2.1.0 tag.
5. Confirm content isolation. Navigate to a page that changed between v2.0 and v2.1 (e.g., an updated API reference). The text should match the source in the v2.1.0 tag, not the main branch.

Trade‑offs and practical checks

Each additional version consumes build minutes and storage. On the free RTD plan, excessive active branches can lengthen queue times; on commercial plans, it raises cost. To keep overhead low:

• Avoid long‑lived feature branches that merely duplicate work; delete them once merged.
• Use tags only for official releases; treat branches as temporary.
• Periodically prune old versions from the Admin → Versions page if they are no longer needed.

You can verify that versioning is working correctly by:

1. Opening Project Admin → Versions and confirming the new tag appears with a Built status.
2. Visiting the live site and using the version dropdown to load each version; the URL should change to /<version>/.
3. Reviewing the build logs for each version to ensure a separate build was triggered.

Actionable closing

Start small: add the .readthedocs.yaml file, push a single release tag, and watch the version picker appear. Once you confirm the isolation works, adopt the same process for every future release. This gives your users a reliable way to access the exact documentation that matches the code they are using, while keeping your documentation source in a single repository.