:orphan:

Configuration file v1 (Deprecated)
==================================

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:

.. code:: yaml

   # .readthedocs.yaml

   build:
     image: latest

   python:
     version: 3.6
     setup_py_install: true


Supported settings
------------------

.. warning::

   When using a v1 configuration file,
   the local settings from the web interface are overridden.

version
~~~~~~~

* Default: 1

.. code-block:: yaml

   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.

.. code-block:: yaml

    # Don't build any extra formats
    formats: []

.. code-block:: yaml

    # 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.

.. code-block:: yaml

   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.

.. code-block:: yaml

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

.. code-block:: yaml

    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: ``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.

.. code-block:: yaml

    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 :ref:`config-file/v1:build.image`,
Read the Docs includes some libraries like scipy, numpy, etc.
See :doc:`/builds` for more details.

.. code-block:: yaml

    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.

.. code-block:: yaml

        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.

.. code-block:: yaml

    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:

.. code-block:: python

    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:

.. code-block:: yaml

    python:
        extra_requirements:
            - tests
            - docs

Behind the scene the following Pip command will be run:

.. prompt:: bash $

    pip install .[tests,docs]


.. _environment file: https://conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html#creating-an-environment-from-an-environment-yml-file
.. _extra requirements: https://setuptools.readthedocs.io/en/latest/userguide/dependency_management.html#optional-dependencies
.. _package default dependencies: https://setuptools.readthedocs.io/en/latest/userguide/dependency_management.html#declaring-required-dependency