Read the Docs YAML Config

Read the Docs now has support for configuring builds with a YAML file. The file, readthedocs.yml (or .readthedocs.yml), must be in the root directory of your project.

Warning

This feature is in a beta state. Please file an issue if you find anything wrong.

Supported Settings

formats

  • Default: htmlzip, pdf, epub
  • Options: htmlzip, pdf, epub, none

The formats of your documentation you want to be built. Choose none 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:
    - none
# Build PDF & ePub
formats:
    - epub
    - pdf

requirements_file

  • Default: None
  • Type: Path (specified from the root of the project)

The path to your Pip requirements file.

requirements_file: requirements/docs.txt

conda

The conda block allows for configuring our support for Conda.

conda.file

  • Default: None
  • 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.

python

The python block allows you to configure aspects of the Python executable used for building documentation.

python.version

  • Default: 2
  • Options: 2, 3

The version of Python to use when building your documentation.

python:
   version: 3

python.setup_py_install

  • 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

python.pip_install

  • Default: False
  • Type: Boolean

When true, install your project into the Virtualenv with pip when building documentation.

python:
   pip_install: true

python.extra_requirements

  • 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:

$ pip install -e .[tests,docs]