Configuration file tutorial

As part of the initial set up for your Read the Docs site, you need to create a configuration file called .readthedocs.yaml. The configuration file tells Read the Docs what specific settings to use for your project.

This tutorial covers:

  1. Where to put your configuration file.

  2. What to put in the configuration file.

  3. How to customize the configuration for your project.

See also

Read the Docs tutorial.

Following the steps in our tutorial will help you setup your first documentation project.

Where to put your configuration file

The .readthedocs.yaml file should be placed in the top-most directory of your project’s repository. We will get to the contents of the file in the next steps.

When you have changed the configuration file, you need to commit and push the changes to your Git repository. Read the Docs will then automatically find and use the configuration to build your project.

Note

The Read the Docs configuration file is a YAML file. YAML is a human-friendly data serialization language for all programming languages. To learn more about the structure of these files, see the YAML language overview.

Getting started with a template

Here are some configuration file examples to help you get started. Pick an example based on the tool that your project is using, copy its contents to .readthedocs.yaml and add the file to your Git repository.

If your project uses Sphinx, we offer a special builder optimized for Sphinx projects.

.readthedocs.yaml
 1# Read the Docs configuration file for Sphinx projects
 2# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
 3
 4# Required
 5version: 2
 6
 7# Set the OS, Python version and other tools you might need
 8build:
 9  os: ubuntu-22.04
10  tools:
11    python: "3.12"
12    # You can also specify other tool versions:
13    # nodejs: "20"
14    # rust: "1.70"
15    # golang: "1.20"
16
17# Build documentation in the "docs/" directory with Sphinx
18sphinx:
19  configuration: docs/conf.py
20  # You can configure Sphinx to use a different builder, for instance use the dirhtml builder for simpler URLs
21  # builder: "dirhtml"
22  # Fail on all warnings to avoid broken references
23  # fail_on_warning: true
24
25# Optionally build your docs in additional formats such as PDF and ePub
26# formats:
27#   - pdf
28#   - epub
29
30# Optional but recommended, declare the Python requirements required
31# to build your documentation
32# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
33# python:
34#   install:
35#     - requirements: docs/requirements.txt

Editing the template

Now that you have a .readthedocs.yaml file added to your Git repository, you should see Read the Docs trying to build your project with the configuration file. The configuration file probably needs some adjustments to accommodate exactly your project setup.

Note

If you added the configuration file in a separate branch, you may have to activate a version for that branch.

If you have added the file in a pull request, you should enable pull request builds.

Skip: file header and comments

There are some parts of the templates that you can leave in place:

Comments

We added comments that explain the configuration options and optional features. These lines begin with a #.

Commented out features

We use the # in front of some popular configuration options. They are there as examples, which you can choose to enable, delete or save for later.

version key

The version key tells the system how to read the rest of the configuration file. The current and only supported version is version 2.

Adjust: build.os

In our examples, we are using Read the Docs’ custom image based on the latest Ubuntu release. Package versions in these images will not change drastically, though will receive periodic security updates.

You should pay attention to this field if your project needs to build on an older version of Ubuntu, or in the future when you need features from a newer Ubuntu.

See also

build.os

Configuration file reference with all values possible for build.os.

Adjust: Python configuration

If you are using Python in your builds, you should define the Python version in build.tools.python.

The python key contains a list of sub-keys, specifying the requirements to install.

  • Use python.install.package to install the project itself as a Python package using pip

  • Use python.install.requirements to install packages from a requirements file

  • Use build.jobs to install packages using Poetry or PDM

See also

build.tools.python

Configuration file reference with all Python versions available for build.tools.python.

python

Configuration file reference for configuring the Python environment activated by build.tools.python.

Adjust: Sphinx and MkDocs version

If you are using either the sphinx or mkdocs builder, then Sphinx or MkDocs will be installed automatically in its latest version.

But we recommend that you specify the version that your documentation project uses. The requirements key is a file path that points to a text (.txt) file that lists the Python packages you want Read the Docs to install.

See also

Use a requirements file for Python dependencies

This guide explains how to specify Python requirements, such as the version of Sphinx or MkDocs.

sphinx

Configuration file reference for configuring the Sphinx builder.

mkdocs

Configuration file reference for configuring the MkDocs builder.

Next steps

There are more configuration options that the ones mentioned in this guide.

After you add a configuration file your Git repository, and you can see that Read the Docs is building your documentation using the file, you should have a look at the complete configuration file reference for options that might apply to your project.

See also

Configuration file v2 (.readthedocs.yaml).

The complete list of all possible .readthedocs.yaml settings, including the optional settings not covered in on this page.

Build process customization

Are familiar with running a command line? Perhaps there are special commands that you know you want Read the Docs to run. Read this guide and learn more about how you add your own commands to .readthedocs.yaml.