Managing Documentation Drift with Read the Docs Versioning

The Problem: Documentation Drift

When your software evolves through multiple major releases, your documentation often suffers from "drift." Users on version 1.2 are often accidentally reading the guide for version 2.0, leading to confusion, support tickets, and a general lack of trust in your technical docs. Manually maintaining separate folders for every version (e.g., /v1.2/index.html) is a maintenance nightmare that scales poorly.

The solution is to decouple the documentation build from a single branch and instead tie it to your version control tags. Read the Docs (RTD) automates this by generating a versioned hosting structure and providing a "flyout" menu—a UI component that allows users to switch between versions without leaving the current page.

How the Version Flyout Works

The flyout menu is a built-in JavaScript component injected by Read the Docs into your Sphinx-generated HTML. It doesn't require you to write custom HTML or manage a complex navigation tree. Instead, it queries the RTD project metadata to see which versions are currently built and available.

By default, RTD recognizes three primary states:

• Latest: Usually mapped to the default branch (e.g., main or master). This is where the most recent, potentially unstable changes live.
• Stable: Mapped to a specific stable branch or the most recent git tag. This is the recommended version for most users.
• Tagged Versions: Specific snapshots of the documentation tied to git tags (e.g., v1.0.4), allowing users to find docs for legacy installations.

Implementing a Versioning Strategy

To make the flyout menu useful, you must align your git tagging strategy with your RTD project settings. If you don't tag your releases in git, the flyout menu will only show "Latest" and "Stable," which is insufficient for software with long-term support (LTS) versions.

Configuration Example

To enable versioning, you don't change your Sphinx conf.py; instead, you configure the project dashboard in Read the Docs. Here is the logical mapping required for a standard release cycle:

RTD Version Label	Git Source	User Intent
Latest	main branch	"I want to see what's coming next."
Stable	v2.0 branch	"I am using the current official release."
v1.5	Tag v1.5.2	"I am maintaining a legacy system."

Actionable Step: To trigger a new version in the flyout, run the following command in your local terminal and push to your remote:

# Create a tag for the current state of docs
git tag -a v1.1.0 -m "Release version 1.1.0"
# Push the tag to GitHub/GitLab
git push origin v1.1.0

Once pushed, the RTD webhook triggers a build for that specific tag. After the build succeeds, the v1.1.0 option automatically appears in the flyout menu for all users.

Trade-offs and Limitations

While the flyout menu is powerful, it has specific technical constraints:

• CSS Conflicts: If you use a highly customized Sphinx theme or aggressive global CSS overrides, the flyout menu's styling may be broken. Since the menu is injected at runtime, it can be overridden by !important declarations in your theme.
• Build Overhead: Every single tag you choose to build consumes build minutes. For projects with hundreds of micro-releases, building every tag is inefficient. It is better to build only major and minor versions (e.g., v1.1, v1.2) rather than every patch (v1.1.1, v1.1.2).
• URL Persistence: If a user bookmarks a page in /latest/, they will always see the latest version, even if a new stable version is released. Encourage users to bookmark the /stable/ path for longevity.

Verifying Your Setup

To ensure your versioning is working correctly, perform these three checks:

1. The Visual Check: Open your live documentation and look for the version selector (usually bottom-left or top-left). Verify that the list matches your intended release versions.
2. The Path Check: Click a version in the flyout. The URL should change from yourproject.readthedocs.io/en/latest/ to yourproject.readthedocs.io/en/v1.1.0/.
3. The Dashboard Check: Log into the Read the Docs dashboard and navigate to Versions. Ensure that the status for each tag is "Built" and not "Failed" or "Pending."