Choosing a Versioning Strategy on Read the Docs: Built‑in vs Separate Projects

The Problem: Choosing a Versioning Strategy

When publishing documentation on Read the Docs (RTD), you must decide how to handle multiple releases. The platform offers two main approaches: using its built‑in versioning system (branches/tags) or creating a separate RTD project for each release. This decision affects build time, storage usage, URL structure, and the ease with which users can switch between versions.

Comparison of Options

Aspect	Built‑in Versioning	Separate Projects	When to Choose
Setup complexity	Low – enable in admin UI, add .readthedocs.yaml	Higher – create a new project per branch/tag	Built‑in for simple repos
Build minutes	Shared quota; each version builds on push	Separate quota per project; can exceed free limits faster	Separate if you need isolated limits
Storage	All versions stored under one project; cumulative size	Each project stores its own copy; duplication possible	Built‑in to save space
URL scheme	https://<project>.readthedocs.io/en/<version>/	https://<project‑<version>>.readthedocs.io/	Built‑in for cleaner paths
Version switching UI	Built‑in dropdown in documentation footer	No native switcher; must provide external links	Built‑in for user convenience

Technical Trade‑offs

Built‑in versioning leverages RTD’s ability to detect Git branches and tags. After you push a new tag, RTD automatically creates a versioned build. The version selector appears in the rendered docs, letting readers jump between releases without leaving the site. The downside is that all versions consume the same project’s build minute quota; a busy repository with many tags can quickly hit the free‑tier 10‑minute limit per build, especially if each version runs heavy Sphinx autodoc.

Separate projects give each release its own isolated build environment and quota. This can be useful when you want to guarantee that an older version’s build never gets pre‑empted by a newer one’s CI, or when you need different dependencies per release (e.g., a legacy version requiring Python 3.7). The trade‑off is extra administrative overhead: you must create a new project, configure its own .readthedocs.yaml (or rely on repo detection), and maintain a mapping from version to URL. Users lose the convenient version dropdown and must rely on external navigation.

Implementation: Enabling Built‑in Versioning

To use RTD’s native versioning, follow these steps. The configuration lives in the repository, so it is version‑controlled.

Step 1: Add a .readthedocs.yaml file

Run these commands in your local repository (you need write access to the repo):

# Ensure you are on the branch you want to configure
git checkout main
# Create the config file
touch .readthedocs.yaml

Insert the following YAML. It tells RTD to use Python 3.11, install Sphinx and a theme, and build with sphinx-build. Adjust the requirements section if you have a requirements.txt or pyproject.toml.

version: 2
build:
  os: ubuntu-22.04
  tools:
    python: \"3.11\"
  jobs:
    install:
      - pip install -r requirements.txt sphinx-rtd-theme
    build:
      - sphinx-build -b html docs _build/html

Risk: If your documentation lives in a folder other than docs/, change the paths accordingly. Missing dependencies cause the install job to fail and the build to be marked as errored.

Step 2: Enable version detection in the RTD dashboard

1. Log in to readthedocs.org and open your project’s admin panel.
2. Navigate to Versions → Active Versions.
3. Toggle the switch for Edit default version if you want a specific tag to be the landing page.
4. Ensure Set up versioning automatically is checked; this tells RTD to monitor new branches and tags.

Validation and Verification

After pushing the .readthedocs.yaml file and creating a new tag, verify the setup:

• Build logs: In the RTD dashboard, open the Builds tab. Look for a build triggered by the tag push. Confirm that the install job ends with Successfully installed messages and that the build job exits with code 0.
• Version selector: Visit the built documentation URL (e.g., https://<project>.readthedocs.io/en/latest/) and check the footer for a dropdown listing all active versions. Selecting an older tag should load its documentation without a 404.
• Search index: Use the search bar to query a term known to exist only in the older version; results should appear when that version is selected.

Limitations and Practical Checks

Even with built‑in versioning, the free tier imposes a 10‑minute ceiling per build. If you notice builds consistently timing out, you can:

• Trim the requirements.txt to only packages needed for doc generation.
• Use sphinx-build -b html -W --keep-going to continue on warnings, reducing re‑runs.
• Consider switching to a paid plan if you need more build minutes or private repositories.

To check whether you are approaching the limit, open the build log and locate the line that reports total elapsed time (e.g., Build finished in 9 minutes 42 seconds). If it regularly exceeds 9 minutes, act on the mitigation steps above.