Building Documentation with Read the Docs

To build and host documentation on Read the Docs in 2026, you do three things: pick a documentation generator (Sphinx or MkDocs), add a .readthedocs.yaml v2 config file to the root of your repository, then connect the repo to Read the Docs so every push and pull request triggers an automatic build. Read the Docs clones your repo, installs your dependencies, runs the generator, and serves the resulting HTML at a public URL with versioning, full-text search, and a flyout menu built in.

The single most important change since older tutorials: the .readthedocs.yaml file is now required, and it must use build.os plus build.tools.python — the old build.image and python.version keys are deprecated and no longer work. This guide shows the current configuration end to end.

Key takeaways

• A .readthedocs.yaml v2 file is mandatory. Put it in your repo root and pin the build environment with build.os (for example ubuntu-24.04) and build.tools.python (for example "3.12").
• Two mainstream toolchains: Sphinx + reStructuredText for deep, reference-grade docs, or MkDocs + Markdown (usually with Material for MkDocs) for fast, approachable docs. Read the Docs hosts both.
• You can write Markdown in Sphinx via MyST-Parser — you do not have to choose reStructuredText to get Sphinx's power.
• Generate API docs from docstrings with Sphinx autodoc (or mkdocstrings for MkDocs) instead of hand-writing reference pages.
• Read the Docs Addons (flyout, server-side search, and pull-request build previews) are the modern default — review rendered docs on every PR before merging.
• Two hosting tiers: a free Community tier for open source and a paid Business tier for private/commercial projects.

What is Read the Docs?

Read the Docs is a documentation-hosting platform that automates the build-and-deploy loop for technical docs. You connect a Git repository (GitHub, GitLab, or Bitbucket); on every commit it checks out your code, creates an isolated environment, installs your documentation dependencies, runs your generator, and publishes the static HTML. It handles the parts that are tedious to self-host: multiple versions (per branch or tag), full-text search, downloadable PDF/ePub, and a flyout menu for switching versions and formats.

It is generator-agnostic for Python projects: it natively supports both Sphinx and MkDocs. Your job is to author the content and declare how to build it; Read the Docs does the rest.

Sphinx or MkDocs: which should you choose?

The first real decision is your generator. Sphinx is the long-standing standard for Python — it powers the CPython, Django, and NumPy docs, and its autodoc extension pulls API reference straight from your docstrings. Its native markup is reStructuredText (reST), though MyST-Parser now lets you author in Markdown. MkDocs is Markdown-first and simpler to start with; paired with the popular Material for MkDocs theme it produces polished sites quickly, and mkdocstrings provides docstring-driven API pages.

Use the table below to decide.

	Sphinx	MkDocs
Default markup	reStructuredText (Markdown via MyST-Parser)	Markdown
Best for	Large, reference-heavy docs and Python libraries	Product/app docs and getting-started guides
API from docstrings	autodoc / autosummary (built-in ecosystem)	mkdocstrings plugin
Popular theme	Furo, sphinx-rtd-theme, PyData	Material for MkDocs
Cross-references	Powerful (:ref:, intersphinx across projects)	Basic, plugin-assisted
Output formats	HTML, PDF, ePub	HTML (PDF via plugin)
Learning curve	Steeper (reST quirks)	Gentle (plain Markdown)
Read the Docs support	First-class	First-class

Rule of thumb: choose Sphinx if you are documenting a Python library or need rich cross-references and PDF output; choose MkDocs + Material if you want a clean docs site up fast and your team prefers Markdown. If you love Sphinx's tooling but dislike reST, use Sphinx with MyST-Parser and write Markdown anyway.

How do I set up Sphinx?

Install Sphinx in your project's virtual environment, then scaffold a docs tree with sphinx-quickstart. It generates a conf.py (your build configuration) and an index.rst (your landing page and table of contents).

# from your project root, inside a virtual environment
python -m pip install sphinx
mkdir docs
cd docs
sphinx-quickstart
# answer the prompts (project name, author, etc.);
# choosing "separate source and build directories" is recommended

The generated conf.py is the heart of a Sphinx build. To pull API documentation from your docstrings and to author pages in Markdown, enable autodoc and myst_parser:

# docs/source/conf.py
project = "My Project"
author = "My Team"
release = "1.0"

extensions = [
    "sphinx.ext.autodoc",      # API docs from docstrings
    "sphinx.ext.napoleon",     # Google / NumPy docstring styles
    "sphinx.ext.intersphinx",  # link to other projects' docs
    "myst_parser",             # write pages in Markdown, not just reST
]

# So Markdown (.md) and reStructuredText (.rst) both work:
source_suffix = {".rst": "restructuredtext", ".md": "markdown"}

html_theme = "furo"  # a clean, modern theme (pip install furo)

The index.rst ties pages together with a toctree directive — the table of contents that defines your docs' structure and navigation:

.. index.rst

Welcome to My Project
=====================

.. toctree::
   :maxdepth: 2
   :caption: Contents

   installation
   usage
   api

Generating API reference from docstrings

The big payoff of Sphinx is autodoc: instead of hand-writing reference pages, you point it at your modules and it renders your docstrings as formatted API docs. In an api.rst (or, with MyST, an api.md):

.. api.rst

API Reference
=============

.. automodule:: mypackage.core
   :members:
   :undoc-members:
   :show-inheritance:

Build the HTML locally to preview before pushing. Sphinx writes the site into a build directory you can open in any browser:

# from the docs/ directory
python -m pip install furo myst-parser
sphinx-build -b html source build/html
# open build/html/index.html in your browser

How do I set up MkDocs instead?

If you prefer Markdown end to end, MkDocs is a fast alternative. Configuration lives in a single mkdocs.yml, and content is plain .md files under docs/.

python -m pip install mkdocs-material
mkdocs new .          # scaffolds mkdocs.yml and docs/index.md
mkdocs serve          # live-reload preview at http://127.0.0.1:8000

# mkdocs.yml
site_name: My Project
theme:
  name: material        # Material for MkDocs
plugins:
  - search
  - mkdocstrings        # API docs from docstrings (pip install mkdocstrings[python])
nav:
  - Home: index.md
  - Installation: installation.md
  - Usage: usage.md
  - API: api.md

The required .readthedocs.yaml v2 config

This is the part most outdated guides get wrong. Read the Docs requires a .readthedocs.yaml file in your repository root, and it must use schema version 2. The environment is pinned with build.os and build.tools.python — the legacy build.image and python.version keys have been removed and will fail the build.

Here is a current, working config for a Sphinx project on Ubuntu 24.04 and Python 3.12:

# .readthedocs.yaml  (Sphinx)
version: 2

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

sphinx:
  configuration: docs/source/conf.py

# Optional: also build downloadable formats
formats:
  - pdf
  - epub

# Install your docs (and project) dependencies
python:
  install:
    - requirements: docs/requirements.txt

For a MkDocs project, swap the sphinx: key for mkdocs::

# .readthedocs.yaml  (MkDocs)
version: 2

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

mkdocs:
  configuration: mkdocs.yml

python:
  install:
    - requirements: docs/requirements.txt

Declaring dependencies

Read the Docs builds in a clean, isolated environment, so it can only install what you declare. Pin your documentation dependencies in a docs/requirements.txt:

# docs/requirements.txt
sphinx>=7.0
furo
myst-parser
# for MkDocs projects instead:
# mkdocs-material
# mkdocstrings[python]

Prefer pyproject.toml? Read the Docs can install your project with its extras instead of a requirements file — useful when autodoc needs to import your package:

# .readthedocs.yaml fragment using pyproject.toml extras
python:
  install:
    - method: pip
      path: .
      extra_requirements:
        - docs   # maps to [project.optional-dependencies].docs in pyproject.toml

Connecting your repo and enabling PR previews

Sign in to Read the Docs with your Git provider, then Add project and select your repository. Read the Docs imports it, reads your .readthedocs.yaml, and runs the first build. After that, every push to a tracked branch rebuilds automatically.

Modern projects should turn on Read the Docs Addons, which are the current default feature set: the version flyout menu, fast server-side search, and — most useful for teams — pull-request build previews. With PR previews enabled, opening a pull request triggers a temporary build so reviewers can read the rendered docs for that change before it merges, catching broken cross-references and bad formatting in review rather than in production.

Community vs Business: the hosting tiers

Read the Docs offers two tiers. The Community tier is free and intended for open-source projects, with docs served publicly. The Business tier is a paid plan for private or commercial documentation, adding private repositories, authenticated access controls, and no third-party ads. Both run the same build pipeline and the same .readthedocs.yaml config, so you can develop against Community conventions and move to Business when you need privacy. (Check the Read the Docs pricing page for current plan details.)

Common build failures and how to fix them

• Build fails with no/old config — confirm .readthedocs.yaml exists in the repo root and starts with version: 2.
• "Unexpected key build.image / python.version" — remove those legacy keys; use build.os and build.tools.python instead.
• autodoc import errors — your package is not installed in the build env; install it via python.install (requirements or pyproject.toml extras) so Sphinx can import it.
• Missing extension or theme — add it to docs/requirements.txt; the build environment is clean and installs only what you declare.
• Markdown not rendering in Sphinx — enable myst_parser in conf.py and register .md in source_suffix.

Frequently Asked Questions

Is a .readthedocs.yaml file required?

Yes. Read the Docs now requires a .readthedocs.yaml configuration file in your repository root, using schema version 2. It must define the build environment with build.os and build.tools.python. The older build.image and python.version keys are deprecated and will cause the build to fail.

Should I use Sphinx or MkDocs for my Python project?

Use Sphinx if you are documenting a Python library or need rich cross-references, intersphinx links, and PDF/ePub output — its autodoc extension generates API docs straight from your docstrings. Use MkDocs with the Material theme if you want a clean docs site quickly and your team prefers writing in plain Markdown. Read the Docs hosts both equally well.

Can I write documentation in Markdown with Sphinx?

Yes. Install and enable MyST-Parser in your conf.py and register .md in source_suffix. You then get Sphinx's full toolchain — autodoc, cross-references, themes, PDF output — while authoring pages in Markdown instead of reStructuredText. You can even mix .md and .rst files in the same project.

How do I generate API documentation from docstrings?

In Sphinx, enable the sphinx.ext.autodoc extension and use the automodule or autoclass directives pointing at your modules; Sphinx renders your docstrings as formatted reference pages. Add sphinx.ext.napoleon to support Google- and NumPy-style docstrings. In MkDocs, the mkdocstrings plugin provides the equivalent docstring-driven API pages.

What are Read the Docs pull-request previews?

PR previews are part of Read the Docs Addons. When you open a pull request, Read the Docs builds a temporary version of your docs for that branch, so reviewers can read the rendered changes before merging. This catches broken links, bad cross-references, and formatting issues during code review instead of after they reach production.

Is Read the Docs free?

Read the Docs has a free Community tier for open-source projects, where documentation is hosted publicly. For private or commercial docs, the paid Business tier adds private repositories, authenticated access, and an ad-free experience. Both tiers use the same build pipeline and the same .readthedocs.yaml configuration, so projects can move between them without rewriting their setup.

Where to go next

Good docs sit alongside good packaging and clean code. If you are shipping a library, pair this with our guides on publishing a Python package to PyPI and Python coding best practices, and if you work in a terminal-first setup, see Vim for Python development.

MicroPyramid has built and maintained Python applications for 12+ years across 50+ delivered projects, including the documentation and developer experience that ship with them. If you want an experienced team to design, build, or modernize your Python product and its docs, explore our Python development services.