Skip to content

Improve yaml config docs #3685

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 7 commits into from
May 22, 2018
Merged

Improve yaml config docs #3685

Changes from 4 commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
0dd7ae9
Add example
stsewd Feb 26, 2018
34fc013
Use yaml types
stsewd Feb 26, 2018
67fed29
Indentation
stsewd Feb 26, 2018
2374e97
Indent
stsewd Feb 26, 2018
6d45d0b
Updat docs about formats to allow to use []
stsewd Mar 6, 2018
5f8b332
Merge branch 'master' into improve-docs-yaml-config
stsewd May 7, 2018
2fb5382
Update formats spec
stsewd May 7, 2018
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
54 changes: 33 additions & 21 deletions docs/yaml-config.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,17 +7,33 @@ The file, ``readthedocs.yml`` (or ``.readthedocs.yml``), must be in the root dir
.. warning:: This feature is in a beta state.
Please file an `issue`_ if you find anything wrong.

Supported Settings

Here is an example of how this file looks like:

.. code:: yaml

# .readthedocs.yml

build:
image: latest

python:
version: 3.6
setup_py_install: true


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

formats
~~~~~~~

* Default: ``htmlzip``, ``pdf``, ``epub``
* Options: ``htmlzip``, ``pdf``, ``epub``, ``none``
* Options: ``htmlzip``, ``pdf``, ``epub``, ``null``
* Type: List of options or ``null``

The formats of your documentation you want to be built.
Choose ``none`` to build none of the formats.
Choose ``null`` 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.
Expand All @@ -26,7 +42,7 @@ Choose ``none`` to build none of the formats.

# Don't build any extra formats
formats:
- none
- null
Copy link
Member Author

@stsewd stsewd Feb 26, 2018 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think this would no work with the current implementation

https://github.com/rtfd/readthedocs-build/blob/daecec8b74af1f55b0ab4c1dd53d9cf6aee20126/readthedocs_build/config/config.py#L399-L409

This should be:

formats: null

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do we have a test that make this example fail?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Won't this change affect current users using it in this way?

Copy link
Member Author

@stsewd stsewd Feb 26, 2018 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Now we have one :) readthedocs/readthedocs-build#43

Won't this change affect current users using it in this way?

The current description doesn't work for any user using it

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Mmm, now I see, this value is hardcoded as a string on the code. What should be done now?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

and now that I know the syntax for an empty list, would be better that this is represented as []

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

👍 on using the formats: [] syntax. This example will produce something we don't want:

In [1]: yaml.load("foo:\n  - null")
Out[1]: {'foo': [None]}


.. code-block:: yaml

Expand All @@ -38,15 +54,14 @@ Choose ``none`` to build none of the formats.
requirements_file
~~~~~~~~~~~~~~~~~

* Default: `None`
* Default: ``null``
* Type: Path (specified from the root of the project)

The path to your Pip requirements file.
The path to your pip requirements file.

.. code-block:: yaml

requirements_file: requirements/docs.txt

requirements_file: requirements/docs.txt

conda
~~~~~
Expand All @@ -56,20 +71,18 @@ The ``conda`` block allows for configuring our support for Conda.
conda.file
``````````

* Default: `None`
* 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
conda:
file: environment.yml

.. note:: Conda is only supported via the YAML file.


build
~~~~~

Expand All @@ -80,7 +93,6 @@ The ``build`` block configures specific aspects of the documentation build.
build.image
```````````


* Default: :djangosetting:`DOCKER_IMAGE`
* Options: ``1.0``, ``2.0``, ``latest``

Expand Down Expand Up @@ -115,9 +127,9 @@ python.version
* Default: ``2.7``
* Options: ``2.7``, ``2``, ``3.5``, ``3``

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

Expand All @@ -134,7 +146,7 @@ will be selected.
python.setup_py_install
```````````````````````

* Default: `False`
* Default: ``false``
* Type: Boolean

When true, install your project into the Virtualenv with
Expand All @@ -148,10 +160,10 @@ When true, install your project into the Virtualenv with
python.pip_install
``````````````````

* Default: `False`
* Default: ``false``
* Type: Boolean

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

.. code-block:: yaml
Expand Down Expand Up @@ -195,7 +207,7 @@ python.extra_requirements

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``.
above is set to ``true``.

Let's say your Python package has a ``setup.py`` which looks like this:

Expand Down