Managing Multiple Docs Versions in ReadTheDocs: Flyout Menu & Version Control Explained

Problem Statement

When a project evolves, its documentation often needs to keep pace with new releases, bug‑fix branches, or experimental features. Users—whether developers or end‑users—expect to find a reliable “stable” copy, a “latest” snapshot, and the ability to view older releases. Without a clear strategy, documentation can become fragmented, leading to 404 errors or confusing version numbers.

Why Versioning Matters

Versioning in ReadTheDocs (RTD) is not just a cosmetic feature; it controls which Git branches or tags are built, how they are labeled, and how users navigate between them. Proper setup ensures:

• Users land on the version they expect (e.g., the most recent stable release).
• Broken links in older docs do not surface in newer builds.
• Build pipelines remain predictable and manageable.

RTD Version Control Basics

RTD automatically watches the Git repository for branches and tags. By default, every branch and tag that matches the regex ^v[0-9]+\.[0-9]+\.[0-9]+$ (e.g., v1.2.3) will trigger a build. You can influence this behavior in two ways:

1. Dashboard settings – In the project’s Versions tab, you can enable or disable specific branches/tags.
2. .readthedocs.yml or .readthedocs.cfg – Declarative configuration that defines which versions are public, which are private, and how aliases map to branches.

Below is a minimal .readthedocs.yml that demonstrates the key concepts:

version: 2
build:
  os: ubuntu-22.04
  tools:
    python: "3.12"

sphinx:
  configuration: docs/conf.py

# Tell RTD which branches/tags to build
# The regex matches tags like v1.0.0 and branches like release-1.0
# If you want to ignore a branch, set its status to "disabled".
# The "aliases" section lets you map friendly names to actual references.
# "stable" will always point to the most recent tag that matches the regex.

# Example: enable only v1.0.0 and v1.1.0, and map "stable" to v1.1.0
# The "latest" alias is automatically created for the default branch (main).

# You can also set a specific branch as the default build.
#default_branch: main

# Optional: build only when a tag is pushed
#build:
#  triggers: ["tags"]

Configuring the Flyout Menu

The flyout menu is a UI component that appears in the bottom‑left corner of every page. It lists all public versions and lets users pick the one they want. RTD’s default theme includes this menu automatically once at least two versions are public.

To ensure the flyout works as intended:

• Make sure at least two versions are marked as public in the dashboard or config.
• Verify that the aliases section contains stable (or any other alias you want to expose).
• After a build, navigate to https://{project}.readthedocs.io/en/{version}/ and look for the version selector.

Example: Setting Up Stable, Latest, and Release Tags

Suppose your repository has the following tags:

• v1.0.0 – first stable release
• v1.1.0 – second stable release
• v2.0.0-beta – pre‑release for the next major version

And you want:

• Users to land on v1.1.0 by default (the most recent stable).
• Expose latest pointing to the main branch for cutting‑edge docs.
• Keep v2.0.0-beta private until it’s ready.

Create a .readthedocs.yml like this:

version: 2

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

sphinx:
  configuration: docs/conf.py

# Version control
# Map 'stable' to the latest tag that matches the pattern v[0-9]+\.[0-9]+\.[0-9]+.
# The regex is evaluated in order; the first match becomes stable.
# For custom ordering, list tags explicitly.

# Public versions
public:
  - main
  - v1.0.0
  - v1.1.0

# Private versions
private:
  - v2.0.0-beta

# Aliases
aliases:
  stable: v1.1.0
  latest: main

Upload this file to the root of your repository and push. In the RTD dashboard, confirm that main, v1.0.0, and v1.1.0 appear under Public versions and that v2.0.0-beta appears under Private versions. After the next build cycle, the flyout menu will show three items: stable (pointing to v1.1.0), latest (main), and v1.0.0. Users can switch between them without leaving the current page.

Trade‑offs & Limitations

• Build Time – Each active version triggers a full Sphinx build. With many tags and branches, build times can grow linearly. Consider disabling or pruning older releases that are no longer needed.
• Alias Accuracy – If you map stable to a branch that later gets deleted, the flyout will show a broken link. Keep the alias mapping in sync with the repo.
• Private Versions – Marking a version as private requires a paid RTD plan. If you need to keep a release hidden from the public, ensure you have the appropriate subscription.
• Configuration Complexity – Mixing dashboard settings with .readthedocs.yml can lead to conflicts. Prefer one source of truth: either the dashboard or the file, but not both.

Actionable Next Steps

1. Add a .readthedocs.yml to your repo root with the desired public and private lists, and alias mappings.
2. Push the file and watch the build status on RTD’s Builds page.
3. After the build succeeds, visit https://{project}.readthedocs.io/en/stable/ to verify the stable version loads.
4. Check the flyout menu on any page; ensure it lists all public versions.
5. Periodically audit the Versions tab to prune obsolete tags or branches and keep build times reasonable.

By following this pattern you give users a clear, reliable path to the documentation they need, while keeping your CI pipeline efficient and maintainable.