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.

Предупреждение

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.

Примечание

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

Примечание

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]