<commit_before>Configuration File V2
=====================

Read the Docs support configuring builds with a YAML file.
The file, ``.readthedocs.yml``, must be in the root directory of your project.

Here is an example of how this file looks like:

.. code:: yaml

   # .readthedocs.yml

   version: 2

   python:
     version: 3.6
     install: pip

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

version
~~~~~~~

* Required

.. code-block:: yaml
   
   version: 2

.. warning::
   
   If you don't provide the version, :doc:`v1 <v1>` would be used.

formats
~~~~~~~

Formats of the documentation to be built.

* Type: ``list``
* Options: ``htmlzip``, ``pdf``, ``epub``
* Default: ``[]``

.. code-block:: yaml

   # Default
   formats: []

.. code-block:: yaml

   # Build PDF & ePub
   formats:
     - epub
     - pdf

.. note::

   You can use the ``all`` keyword to indicate all formats.

   .. code-block:: yaml

      # Build all formats
      formats: all

python
~~~~~~

Configuration of the Python environment to be used.

.. code-block:: yaml

   python:
      version: 3.6
      requirements: docs/requirements.txt
      install: pip
      extra_requirements:
        - docs
      system_packages: true

python.version
``````````````

The Python version (this depends on :ref:`config-file/v2:build.image`).

* Type: ``number``
* Default: ``3``

python.requirements
```````````````````

The path to the requirements file from the root of the project.

* Type: ``path``
* Default: ``null``

If the value is ``null``,
Read the Docs would try to find a requirements file in your ``docs/`` directory and in the root of your project.
If you want to completely ignore the requirements file, you can use an empty string ``''``.

python.install
``````````````

Install the project using python ``python setup.py install`` or ``pip install .``.

* Type: ``string``
* Options: ``pip``, ``setup.py``
* Default: ``null``

python.extra_requirements
`````````````````````````

`Extra requirements <https://setuptools.readthedocs.io/en/latest/setuptools.html#declaring-extras-optional-features-with-their-own-dependencies>`_
section to install in addition to the `package dependencies <https://setuptools.readthedocs.io/en/latest/setuptools.html#declaring-dependencies>`_.

* Type: ``list``
* Default: ``[]``

.. warning::

   You need to install your project with ``pip`` to use this feature.
   See :ref:`config-file/v2:python.install`.

Behind the scene the following Pip command will be run::

   $ pip install -e .[tests,docs]

python.system_packages
``````````````````````

Give the virtual environment access to the global site-packages directory.

* Type: ``bool``
* Default: ``false``

conda
~~~~~

Configuration for Conda support.

.. code-block:: yaml

   conda:
     environment: environment.yml

conda.environment
`````````````````

The path to the Conda environment file from the root of the project.

* Type: ``path``
* Required

build
~~~~~

Configuration for the documentation build process.

.. code-block:: yaml

   build:
     image: latest

   python:
     version: 3.6


build.image
```````````

The build Docker image to be used.

* Type: ``string``
* Options: ``stable``, ``latest``

Each image support different Python versions and has different packages installed,
as defined here:

* `stable <https://github.com/rtfd/readthedocs-docker-images/tree/3.0.0>`_: 2, 2.7, 3, 3.3, 3.4, 3.5, 3.6
* `latest <https://github.com/rtfd/readthedocs-docker-images/tree/releases/3.x>`_: 2, 2.7, 3, 3.3, 3.4, 3.5, 3.6

sphinx
~~~~~~

Configuration for Sphinx documentation
(this is the default documentation type).

.. code-block:: yaml

   sphinx:
     builder: html
     configuration: conf.py
     fail_on_warning: true

sphinx.builder
``````````````

sphinx.configuration
````````````````````

The path to the ``conf.py`` file.<commit_msg>Add docs for sphinx.buider<commit_after>Configuration File V2
=====================

Read the Docs support configuring builds with a YAML file.
The file, ``.readthedocs.yml``, must be in the root directory of your project.

Here is an example of how this file looks like:

.. code:: yaml

   # .readthedocs.yml

   version: 2

   python:
     version: 3.6
     install: pip

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

version
~~~~~~~

* Required

.. code-block:: yaml
   
   version: 2

.. warning::
   
   If you don't provide the version, :doc:`v1 <v1>` would be used.

formats
~~~~~~~

Formats of the documentation to be built.

* Type: ``list``
* Options: ``htmlzip``, ``pdf``, ``epub``
* Default: ``[]``

.. code-block:: yaml

   # Default
   formats: []

.. code-block:: yaml

   # Build PDF & ePub
   formats:
     - epub
     - pdf

.. note::

   You can use the ``all`` keyword to indicate all formats.

   .. code-block:: yaml

      # Build all formats
      formats: all

python
~~~~~~

Configuration of the Python environment to be used.

.. code-block:: yaml

   python:
      version: 3.6
      requirements: docs/requirements.txt
      install: pip
      extra_requirements:
        - docs
      system_packages: true

python.version
``````````````

The Python version (this depends on :ref:`config-file/v2:build.image`).

* Type: ``number``
* Default: ``3``

python.requirements
```````````````````

The path to the requirements file from the root of the project.

* Type: ``path``
* Default: ``null``

If the value is ``null``,
Read the Docs would try to find a requirements file in your ``docs/`` directory and in the root of your project.
If you want to completely ignore the requirements file, you can use an empty string ``''``.

python.install
``````````````

Install the project using python ``python setup.py install`` or ``pip install .``.

* Type: ``string``
* Options: ``pip``, ``setup.py``
* Default: ``null``

python.extra_requirements
`````````````````````````

`Extra requirements <https://setuptools.readthedocs.io/en/latest/setuptools.html#declaring-extras-optional-features-with-their-own-dependencies>`_
section to install in addition to the `package dependencies <https://setuptools.readthedocs.io/en/latest/setuptools.html#declaring-dependencies>`_.

* Type: ``list``
* Default: ``[]``

.. warning::

   You need to install your project with ``pip`` to use this feature.
   See :ref:`config-file/v2:python.install`.

Behind the scene the following Pip command will be run::

   $ pip install -e .[tests,docs]

python.system_packages
``````````````````````

Give the virtual environment access to the global site-packages directory.

* Type: ``bool``
* Default: ``false``

conda
~~~~~

Configuration for Conda support.

.. code-block:: yaml

   conda:
     environment: environment.yml

conda.environment
`````````````````

The path to the Conda environment file from the root of the project.

* Type: ``path``
* Required

build
~~~~~

Configuration for the documentation build process.

.. code-block:: yaml

   build:
     image: latest

   python:
     version: 3.6


build.image
```````````

The build Docker image to be used.

* Type: ``string``
* Options: ``stable``, ``latest``

Each image support different Python versions and has different packages installed,
as defined here:

* `stable <https://github.com/rtfd/readthedocs-docker-images/tree/3.0.0>`_: 2, 2.7, 3, 3.3, 3.4, 3.5, 3.6
* `latest <https://github.com/rtfd/readthedocs-docker-images/tree/releases/3.x>`_: 2, 2.7, 3, 3.3, 3.4, 3.5, 3.6

sphinx
~~~~~~

Configuration for Sphinx documentation
(this is the default documentation type).

.. code-block:: yaml

   sphinx:
     builder: html
     configuration: conf.py
     fail_on_warning: true

sphinx.builder
``````````````

The builder type for the Sphinx documentation.

* Type: ``string``
* Options: ``html``, ``htmldir``, ``singlehtml``
* Default: ``html``

sphinx.configuration
````````````````````

The path to the ``conf.py`` file.
{'fraction_non_alphanumeric': 0.17603474706182934, 'fraction_numerical': 0.010730710270822688, 'mean_word_length': 3.483963344788087, 'pattern_counts': {'":': 0, '<': 13, '<?xml version=': 0, '>': 13, 'https://': 8, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '4589987', 'n_tokens_mistral': 2673, 'n_tokens_neox': 2443, 'n_words': 811}