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.

参考

/tutorial/index.

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.

注釈

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.

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.

注釈

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.

参考

config-file/v2: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

参考

config-file/v2:build.tools.python

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

config-file/v2: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.

参考

guides/reproducible-builds:Use a requirements file for Python dependencies

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

config-file/v2:sphinx

Configuration file reference for configuring the Sphinx builder.

config-file/v2: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.

参考

/config-file/v2.

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

/build-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.