Configuration file overview
As part of the initial set up of a Read the Docs project,
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:
Where to put your configuration file
The .readthedocs.yaml
file should be placed in the top-most directory of your project’s repository.
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.
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
If your project uses MkDocs, we offer a special builder optimized for MkDocs projects.
1# Read the Docs configuration file for MkDocs projects
2# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
3
4# Required
5version: 2
6
7# Set the version of Python and other tools you might need
8build:
9 os: ubuntu-22.04
10 tools:
11 python: "3.12"
12
13mkdocs:
14 configuration: mkdocs.yml
15
16# Optionally declare the Python requirements required to build your docs
17python:
18 install:
19 - requirements: docs/requirements.txt
You can find more information about these tools in our Supported tools.
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:
version
keyThe version key tells the system how to read the rest of the configuration file. The current and only supported version is version 2.
- 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.
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.path
to install the project itself as a Python package using pipUse
python.install.requirements
to install packages from a requirements fileUse
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 reference.
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
.