orphan: |
---|
Read the Docs has support for configuring builds with a YAML file. :doc:`The Read the Docs file <index>` must be in the root directory of your project.
Warning
Version 1 is deprecated and :doc:`support will be removed in September 2023 <rtd-blog:migrate-configuration-v2>`. You should use version 2 of the configuration file. See the :ref:`new features <config-file/v2:New settings>` and :ref:`how to migrate from v1 <config-file/v2:Migrating from v1>`.
Here is an example of what this file looks like:
# .readthedocs.yaml
build:
image: latest
python:
version: 3.6
setup_py_install: true
Warning
When using a v1 configuration file, the local settings from the web interface are overridden.
- Default: 1
version: 1
- Default: [
htmlzip
,pdf
,epub
] - Options:
htmlzip
,pdf
,epub
- Type: List
The formats of your documentation you want to be built.
Set as an empty list []
to build none of the formats.
Note
We will always build an HTML & JSON version of your documentation. These are used for web serving & search indexing, respectively.
# Don't build any extra formats
formats: []
# Build PDF & ePub
formats:
- epub
- pdf
- Default:
null
- Type: Path (specified from the root of the project)
The path to your pip requirements file.
requirements_file: requirements/docs.txt
The conda
block allows for configuring our support for Conda.
- Default:
null
- Type: Path (specified from the root of the project)
The file option specified the Conda environment file to use.
conda:
file: environment.yml
Note
Conda is only supported via the YAML file.
The build
block configures specific aspects of the documentation build.
- Default:
latest
- Options:
stable
,latest
The build image to use for specific builds. This lets users specify a more experimental build image, if they want to be on the cutting edge.
Certain Python versions require a certain build image, as defined here:
stable
:2
,2.7
,3
,3.5
,3.6
,3.7
latest
:2
,2.7
,3
,3.5
,3.6
,3.7
,3.8
build:
image: latest
python:
version: 3.6
The python
block allows you to configure aspects of the Python executable
used for building documentation.
- Default:
3.7
- Options:
2
,2.7
,3
,3.5
,3.6
,3.7
,3.8
This is the version of Python to use when building your documentation. If you specify only the major version of Python, the highest supported minor version will be selected.
Warning
The supported Python versions depends on the version of the build image your
project is using. The default build image that is used to build
documentation contains support for Python 2.7
and 3.7
.
See :ref:`config-file/v1:build.image` for more information on supported Python versions.
python:
version: 3.5
- Default:
false
- Type: Boolean
When true, install your project into the Virtualenv with
python setup.py install
when building documentation.
python:
setup_py_install: true
- Default:
false
- Type: Boolean
When true
, install your project into the virtualenv with pip when building
documentation.
python:
pip_install: true
- Default:
[]
- Type: List
List of extra requirements sections to install, additionally to the
package default dependencies. Only works if python.pip_install
option
above is set to true
.
Let's say your Python package has a setup.py
which looks like this:
from setuptools import setup
setup(
name="my_package",
# (...)
install_requires=["requests", "simplejson"],
extras_require={
"tests": ["nose", "pycodestyle >= 2.1.0"],
"docs": ["sphinx >= 1.4", "sphinx_rtd_theme"],
},
)
Then to have all dependencies from the tests
and docs
sections
installed in addition to the default requests
and simplejson
, use the
extra_requirements
as such:
python:
extra_requirements:
- tests
- docs
Behind the scene the following Pip command will be run:
.. prompt:: bash $ pip install .[tests,docs]