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
an be named .readthedocs.yaml
.
All options are applied to the version containing this file. Below is an example YAML file which shows the most common configuration options:
# .readthedocs.yaml
# 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.yaml
# 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 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¶
- 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 /bareos/config-file/v2: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 /bareos/config-file/v2:build.image, Read the Docs includes some libraries like scipy, numpy, etc. That you can access to them by enabling this option. See /bareos/builds 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:
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 inseq
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 /bareos/config-file/v2: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 inseq
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.
Migrating from v1¶
Changes¶
The version setting is required. See /bareos/config-file/v2:version.
The default value of the /bareos/config-file/v2:formats setting has changed to
[]
and it doesn’t include the values from the web interface.The top setting
requirements_file
was moved topython.install
and we don’t try to find a requirements file if the option isn’t present. See /bareos/config-file/v2:Requirements file.The setting
conda.file
was renamed toconda.environment
. See /bareos/config-file/v2:conda.environment.The
build.image
setting now only has two options:latest
(default) andstable
. See /bareos/config-file/v2:build.image.The settings
python.setup_py_install
andpython.pip_install
were replaced bypython.install
. And now it accepts a path to the package. See /bareos/config-file/v2:Packages.The setting
python.use_system_site_packages
was renamed topython.system_packages
. See /bareos/config-file/v2: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 /bareos/config-file/v2:Migrating from the web interface if you have settings there.
New settings¶
/bareos/config-file/v2:sphinx
/bareos/config-file/v2:mkdocs
/bareos/config-file/v2:submodules
/bareos/config-file/v2:python.install
/bareos/config-file/v2:search
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