Read the Docs Builds vs Publishing to Pages

Read the Docs builds your Sphinx or MkDocs project from a .readthedocs.yaml config on every push, an alternative to running the doc build yourself and pushing to GitHub Pages.

You either let Read the Docs host and build your docs, or you run the builder in your own CI and deploy to Pages. This page covers the config that drives RTD and how the two models differ.

What it does

Read the Docs clones your repo, reads .readthedocs.yaml, installs the build tool and dependencies, runs the builder (Sphinx or MkDocs), and hosts the result with versioning and search. Self-publishing instead runs sphinx-build/mkdocs build in your CI and uploads the output to Pages.

Minimal .readthedocs.yaml

.readthedocs.yaml

version: 2
build:
  os: ubuntu-24.04
  tools:
    python: "3.12"
sphinx:
  configuration: docs/conf.py
python:
  install:
    - requirements: docs/requirements.txt

RTD vs GitHub Pages

Concern	Read the Docs	GitHub Pages + CI
Build	RTD runs it from .readthedocs.yaml	You run sphinx-build / mkdocs build
Versioning	Built in (per tag/branch)	Manual (e.g. mike for MkDocs)
Search	Hosted server-side search	Client-side only
Hosting	readthedocs.io subdomain or custom	github.io or custom domain

In CI

With RTD, keep the doc build reproducible by pinning tool versions in .readthedocs.yaml and dependencies in a requirements file. To leave RTD for Pages, move the exact sphinx-build -b html -W command into your workflow and add an actions/deploy-pages step. Test the build locally either way.

Common errors in CI

Problem in your project's configuration. Invalid "python.version" means the RTD config schema changed; use the build.tools.python form shown above. Config validation error points at a malformed .readthedocs.yaml. A build that works locally but fails on RTD usually means a dependency missing from docs/requirements.txt.