Configuration File V2¶

Read the Docs supports configuring your documentation builds with a YAML file. The configuration file must be in the root directory of your project. We recommend the filename .readthedocs.yml.

All options are applied to the version containing this file. Below is an example YAML file which shows the most common configuration options:

# .readthedocs.yml
# Read the Docs configuration file
# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details

# Required
version: 2

# Build documentation in the docs/ directory with Sphinx
sphinx:
   configuration: docs/conf.py

# Optionally build your docs in additional formats such as PDF
formats:
   - pdf

# Optionally set the version of Python and requirements required to build your docs
python:
   version: 3.7
   install:
   - requirements: docs/requirements.txt

# .readthedocs.yml
# Read the Docs configuration file
# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details

# Required
version: 2

mkdocs:
  configuration: mkdocs.yml

# Optionally build your docs in additional formats such as PDF
formats:
   - pdf

# Optionally set the version of Python and requirements required to build your docs
python:
   version: 3.7
   install:
   - requirements: docs/requirements.txt

Supported settings¶

Read the Docs validates every configuration file. Any configuration option that isn’t supported will make the build fail. This is to avoid typos and provide feedback on invalid configurations.

version
formats
python
conda
build
sphinx
mkdocs
submodules
search

version ¶

Required: true

Example:

version: 2

Warning

If you don’t provide the version, v1 will be used.

formats ¶

Formats of the documentation to be built.

Type: list
Options: htmlzip, pdf, epub
Default: []

Example:

version: 2

# Default
formats: []

version: 2

# Build PDF & ePub
formats:
  - epub
  - pdf

Note

You can use the all keyword to indicate all formats.

version: 2

# Build all formats
formats: all

Warning

pdf, epub, and htmlzip output is not supported when using MkDocs.

python ¶

Configuration of the Python environment to be used.

version: 2

python:
  version: 3.7
  install:
    - requirements: docs/requirements.txt
    - method: pip
      path: .
      extra_requirements:
        - docs
    - method: setuptools
      path: another/package
  system_packages: true

python.version¶

The Python version (this depends on build.image).

Type: number
Default: 3

Warning

If you are using a Conda environment to manage the build, this setting will not have any effect, as the Python version is managed by Conda.

python.install¶

List of installation methods of packages and requirements. You can have several of the following methods.

Type: list
Default: []

Requirements file¶

Install packages from a requirements file.

The path to the requirements file, relative to the root of the project.

Key: requirements
Type: path
Required: true

Example:

version: 2

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

Warning

If you are using a Conda environment to manage the build, this setting will not have any effect. Instead add the extra requirements to the environment file of Conda.

Packages¶

Install the project using python setup.py install or pip install.

The path to the package, relative to the root of the project.

Key: path
Type: path
Required: true

The installation method.

Key: method
Options: pip, setuptools
Default: pip

Extra requirements section to install in addition to the package dependencies.

Warning

You need to install your project with pip to use extra_requirements.

Key: extra_requirements
Type: list
Default: []

Example:

version: 2

python:
  version: 3.7
  install:
    - method: pip
      path: .
      extra_requirements:
        - docs
    - method: setuptools
      path: package

With the previous settings, Read the Docs will execute the next commands:

pip install .[docs]
python package/setup.py install

python.system_packages¶

Give the virtual environment access to the global site-packages directory.

Type: bool
Default: false

Depending on the build.image, Read the Docs includes some libraries like scipy, numpy, etc. That you can access to them by enabling this option. See Build Process for more details.

Warning

If you are using a Conda environment to manage the build, this setting will not have any effect, since the virtual environment creation is managed by Conda.

conda ¶

Configuration for Conda support.

version: 2

conda:
  environment: environment.yml

conda.environment¶

The path to the Conda environment file, relative to the root of the project.

Type: path
Required: true

build ¶

Configuration for the documentation build process.

version: 2

build:
  image: latest

python:
  version: 3.7

build.image¶

The Docker image used for building the docs.

Type: string
Options: stable, latest
Default: latest

Each image support different Python versions and has different packages installed, as defined here:

stable: 2, 2.7, 3, 3.5, 3.6, 3.7, pypy3.5
latest: 2, 2.7, 3, 3.5, 3.6, 3.7, 3.8, pypy3.5

sphinx ¶

Configuration for Sphinx documentation (this is the default documentation type).

version: 2

sphinx:
  builder: html
  configuration: conf.py
  fail_on_warning: true

sphinx.builder¶

The builder type for the Sphinx documentation.

Type: string
Options: html, dirhtml, singlehtml
Default: html

Note

The htmldir builder option was renamed to dirhtml to use the same name as sphinx. Configurations using the old name will continue working.

sphinx.configuration¶

The path to the conf.py file, relative to the root of the project.

Type: path
Default: null

If the value is null, Read the Docs will try to find a conf.py file in your project.

sphinx.fail_on_warning¶

Turn warnings into errors (-W and --keep-going options). This means the build fails if there is a warning and exits with exit status 1.

Type: bool
Default: false

mkdocs ¶

Configuration for Mkdocs documentation.

version: 2

mkdocs:
  configuration: mkdocs.yml
  fail_on_warning: false

mkdocs.configuration¶

The path to the mkdocs.yml file, relative to the root of the project.

Type: path
Default: null

If the value is null, Read the Docs will try to find a mkdocs.yml file in your project.

mkdocs.fail_on_warning¶

Turn warnings into errors. This means that the build stops at the first warning and exits with exit status 1.

Type: bool
Default: false

submodules ¶

VCS submodules configuration.

Note

Only Git is supported at the moment.

Warning

You can’t use include and exclude settings for submodules at the same time.

version: 2

submodules:
  include:
    - one
    - two
  recursive: true

submodules.include¶

List of submodules to be included.

Type: list
Default: []

Note

You can use the all keyword to include all submodules.

version: 2

submodules:
  include: all

submodules.exclude¶

List of submodules to be excluded.

Type: list
Default: []

Note

You can use the all keyword to exclude all submodules. This is the same as include: [].

version: 2

submodules:
  exclude: all

submodules.recursive¶

Do a recursive clone of the submodules.

Type: bool
Default: false

Note

This is ignored if there aren’t submodules to clone.

search ¶

Settings for more control over Server Side Search.

version: 2

search:
  ranking:
    api/v1/*: -1
    api/v2/*: 4
  ignore:
    - 404.html

search.ranking¶

Set a custom search rank over pages matching a pattern.

Type: map of patterns to ranks
Default: {}

Patterns are matched against the final html pages produced by the build (you should try to match index.html, not docs/index.rst). Patterns can include some special characters:

* matches everything
? matches any single character
[seq] matches any character in seq

The rank can be an integer number between -10 and 10 (inclusive). Pages with a rank closer to -10 will appear further down the list of results, and pages with a rank closer to 10 will appear higher in the list of results. Note that 0 means normal rank, not no rank.

If you are looking to completely ignore a page, check search.ignore.

version: 2

search:
  ranking:
    # Match a single file
    tutorial.html: 2

    # Match all files under the api/v1 directory
    api/v1/*: -5

    # Match all files that end with tutorial.html
    '*/tutorial.html': 3

Note

The final rank will be the last pattern to match the page.

Tip

Is better to decrease the rank of pages you want to deprecate, rather than increasing the rank of the other pages.

search.ignore¶

Don’t index files matching a pattern. This is, you won’t see search results from these files.

Type: list of patterns
Default: ['search.html', 'search/index.html', '404.html', '404/index.html']

Patterns are matched against the final html pages produced by the build (you should try to match index.html, not docs/index.rst). Patterns can include some special characters:

* matches everything
? matches any single character
[seq] matches any character in seq

version: 2

search:
   ignore:
     # Ignore a single file
     - 404.html

     # Ignore all files under the search/ directory
     - search/*

     # Ignore all files that end with ref.html
     - '*/ref.html'

version: 2

search:
   ignore:
     # Custom files to ignore
     - file.html
     - api/v1/*

     # Defaults
     - search.html
     - search/index.html
     - 404.html
     - 404/index.html'

Note

Since Read the Docs fallbacks to the original search engine when no results are found, you may still see search results from ignored pages.

Schema¶

You can see the complete schema here.

Migrating from v1¶

Changes¶

The version setting is required. See version.
The default value of the formats setting has changed to [] and it doesn’t include the values from the web interface.
The top setting requirements_file was moved to python.install and we don’t try to find a requirements file if the option isn’t present. See Requirements file.
The setting conda.file was renamed to conda.environment. See conda.environment.
The build.image setting now only has two options: latest (default) and stable. See build.image.
The settings python.setup_py_install and python.pip_install were replaced by python.install. And now it accepts a path to the package. See Packages.
The setting python.use_system_site_packages was renamed to python.system_packages. See python.system_packages.
The build will fail if there are invalid keys (strict mode).

Warning

Some values from the web interface are no longer respected, please see Migrating from the web interface if you have settings there.

Migrating from the web interface¶

This should be pretty straightforward, just go to the Admin > Advanced settings, and find their respective setting in here.

Not all settings in the web interface are per version, but are per project. These settings aren’t supported via the configuration file.

Name
Repository URL
Repository type
Language
Programming language
Project homepage
Tags
Single version
Default branch
Default version
Show versions warning
Privacy level
Analytics code