How to Enable Automatic Versioned Docs on Read the Docs with .readthedocs.yaml

Why You Need Automatic Versioning

Most open‑source projects maintain multiple releases. Users often need to read docs that match the code they’re running. Read the Docs can automatically create a distinct documentation build for each Git tag or branch, eliminating manual uploads and keeping the docs in sync with the source.

Set Up the .readthedocs.yaml File

The .readthedocs.yaml file tells Read the Docs how to build your project. It must live at the root of the repository and be committed to the branch you want to build.

# .readthedocs.yaml
build:
  os: ubuntu-22.04
  tools:
    python: "3.11"
  commands:
    - pip install -r requirements.txt
    - sphinx-build -b html docs/source docs/build/html
# Optional: specify which branches or tags to build
# (if omitted, all tags and branches are built)
# version:
#   - master
#   - "v*"

Key points:

• Python version – choose the runtime that matches your Sphinx setup.
• Build commands – the sequence Read the Docs runs. The example installs dependencies and runs Sphinx.
• Version patterns – by default every tag and branch is built. You can restrict this with the version key.

Tagging and Triggering Builds

Once the configuration file is in place, create a tag in your Git repository:

# Create a lightweight tag
git tag v1.0.0
# Push the tag to the remote
git push origin v1.0.0

Read the Docs monitors the remote repository via a webhook. When it receives the new tag, it:

• Creates a new version entry in the project dashboard.
• Runs the build process defined in .readthedocs.yaml.
• If successful, publishes the HTML under /v1.0.0/ on your project URL.

Verifying the Result

After pushing the tag, check the build status:

1. Navigate to https://readthedocs.org/dashboard/ and open your project.
2. Locate the new version entry (e.g., v1.0.0) and confirm the status is Success.
3. Open the build log to see the Sphinx command executed.
4. Visit https:///v1.0.0/ and verify the docs load correctly.
5. In the UI, the version selector should now list v1.0.0 alongside any other active versions.

Common Pitfalls and Limits

• Webhook misconfiguration – if the webhook is not active, new tags will not trigger builds. Verify under the project settings that the Git provider webhook is enabled.
• Invalid version names – version strings must be URL‑safe. Avoid spaces, slashes, or characters that could clash with reserved paths like latest or stable unless you intentionally want to override them.
• Missing .readthedocs.yaml – without this file, Read the Docs falls back to legacy configuration and may not build new tags.
• Private repositories – ensure the integration has the necessary permissions and that the webhook can reach Read the Docs. Public repos trigger builds automatically; private repos require an access token.
• Build time limits – large projects can exceed the default build time (typically 30 minutes). If builds fail, consider splitting documentation or optimizing the build steps.
• Active versions quota – paid plans allow more active versions. On the free tier, older versions may be automatically archived if the limit is exceeded.

By following this workflow, you can keep your documentation in sync with every release, reduce manual effort, and provide users with the exact docs they need for the version of your software they’re using.