Skip to content

Latest commit

 

History

History
289 lines (193 loc) · 6.14 KB

v1.rst

File metadata and controls

289 lines (193 loc) · 6.14 KB
Raw

Configuration File V1

Read the Docs now has support for configuring builds with a YAML file. The Read the Docs file <index> must be in the root directory of your project.

Warning

Version 1 shouldn't be used. The version 2 of the configuration file is now avaliable. See the new features <config-file/v2:New settings> and how to migrate from v1 <config-file/v2:Migrating from v1>.

Here is an example of what this file looks like:

# .readthedocs.yml

build:
  image: latest

python:
  version: 3.6
  setup_py_install: true

Supported settings

version

  • Default: 1
version: 1

formats

  • 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

requirements_file

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

build

The build block configures specific aspects of the documentation build.

build.image

  • Default: DOCKER_DEFAULT_VERSION
  • 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: stable
  • latest: latest
build:
    image: latest

python:
    version: 3.6

python

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

python.version

  • Default: 3.7
  • Options: latest

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 config-file/v1:build.image for more information on supported Python versions.

python:
   version: 3.5

python.use_system_site_packages

  • Default: false
  • Type: Boolean

When true, it gives the virtual environment access to the global site-packages directory. Depending on the config-file/v1:build.image, Read the Docs includes some libraries like scipy, numpy, etc. See builds:The build environment for more details.

python:
   use_system_site_packages: true

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:

bash $

pip install .[tests,docs]