Read the Docs: Documentation Hosting for Python Projects

Read the Docs is a hosted documentation platform that watches a Git repository for pushes and automatically builds, versions, and serves the resulting documentation at a stable public URL. It hosts over 100,000 open-source projects, including Flask, Jupyter, and Godot.

When to Use Read the Docs

Read the Docs fits projects that need documentation to stay in sync with code automatically, version management across release branches and tags without manual deployment steps, or pull request previews so reviewers can read rendered docs before merging. GitHub Pages is an alternative for projects that want full control over HTML output and have no requirement for automatic versioning, but it requires a separate CI pipeline to build and push; Read the Docs handles those steps without additional configuration.

Key Features

• Automatic builds triggered by Git pushes
• Versioned documentation: each active branch and tag gets its own URL (/en/stable/, /en/1.0/)
• Pull request previews for every open PR
• Built-in full-text search across all hosted content
• Custom domains with HTTPS (paid tiers)
• Traffic analytics showing which pages readers visit
• Redirect management for moved or deleted pages
• .readthedocs.yaml build configuration file for reproducible builds
• Supports Sphinx, MkDocs, Docusaurus, and other static site generators
• Native uv support for Python dependency installation (added April 2026)

Configuration

A .readthedocs.yaml file at the repo root controls the build environment and dependency installation. The configuration below uses native uv support with a docs dependency group:

version: 2

build:
  os: ubuntu-24.04
  tools:
    python: "3.13"

python:
  install:
    - method: uv
      command: sync
      groups:
        - docs

Read the Docs runs uv sync against pyproject.toml and installs the docs dependency group. Committing uv.lock makes every build install the same resolved versions. See How to Build Read the Docs with uv for the full walkthrough.

Version Management

Read the Docs creates a documentation version for each branch and tag that the project activates. The stable alias points to the highest SemVer tag; latest tracks the default branch. Inactive branches stay in the database but do not render or consume build resources. Automation rules (below) handle version activation automatically in response to Git events.

Automation Rules

Automation rules evaluate incoming webhooks in list order. Each rule has three components:

1. Version type: match tags, branches, pull requests, or any combination.
2. Name pattern: Any version, SemVer versions, or a custom regex.
3. Webhook filters (GitHub App integration only): match on changed files (glob), commit message (regex), or pull request labels (regex). All configured filters must match for the rule to fire.

Supported actions include activating, hiding, making public or private, setting as default, deleting versions, and triggering a build.

Build gating: when any rule includes the “Trigger build for version” action, Read the Docs stops building every push and builds only when a rule matches. This allows a project to skip doc builds for commits that touch only application code. Rules can be disabled temporarily without losing their configuration.

The webhook filter support for changed files, commit messages, and PR labels was introduced in automation rules v2 (June 2026). GitHub App integration is required; the legacy GitHub service hook does not expose the webhook payload these filters inspect.

Pros

• No deployment infrastructure required: every push triggers a build without a CI pipeline
• Versioning and PR previews work immediately after connecting the repository
• Community tier is free and covers the full core feature set for open-source projects
• Integrates with Sphinx, MkDocs, and other documentation generators without per-project setup
• Automation rules v2 support file-level build gating, reducing unnecessary builds on large repositories

Cons

• Community tier documentation displays ads; ads appear inline in the hosted content
• Concurrency limits on the free tier mean simultaneous pushes queue behind each other
• Webhook filter support in automation rules requires the GitHub App; the older GitHub service hook integration does not support it
• Private repositories require the paid Business tier
• Build customization beyond .readthedocs.yaml defaults requires the build.jobs escape hatch, which is verbose for simple needs

Learn More

• Read the Docs Documentation
• .readthedocs.yaml configuration reference
• Automation rules reference
• GitHub Repository
• How to Build Read the Docs with uv configures .readthedocs.yaml for uv sync and lockfile-reproducible doc builds
• How to Set Up Documentation for a Python Package with Sphinx or MkDocs scaffolds the documentation source tree that Read the Docs builds
• Sphinx is the most common documentation generator used with Read the Docs
• MkDocs is the second most common documentation generator used with Read the Docs