From 0dd7ae9ba64c8a0429848ed677096672db12ff05 Mon Sep 17 00:00:00 2001 From: Santos Gallegos Date: Mon, 26 Feb 2018 14:54:51 -0500 Subject: [PATCH 1/6] Add example --- docs/yaml-config.rst | 17 ++++++++++++++++- 1 file changed, 16 insertions(+), 1 deletion(-) diff --git a/docs/yaml-config.rst b/docs/yaml-config.rst index 6fce83495db..9aecbc3b4f2 100644 --- a/docs/yaml-config.rst +++ b/docs/yaml-config.rst @@ -7,7 +7,22 @@ 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 From 34fc01385a2083ebe12ab6ebff077e982c184de1 Mon Sep 17 00:00:00 2001 From: Santos Gallegos Date: Mon, 26 Feb 2018 15:07:27 -0500 Subject: [PATCH 2/6] Use yaml types --- docs/yaml-config.rst | 31 ++++++++++++++----------------- 1 file changed, 14 insertions(+), 17 deletions(-) diff --git a/docs/yaml-config.rst b/docs/yaml-config.rst index 9aecbc3b4f2..ee7cb7fbcbb 100644 --- a/docs/yaml-config.rst +++ b/docs/yaml-config.rst @@ -29,10 +29,11 @@ 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. @@ -41,7 +42,7 @@ Choose ``none`` to build none of the formats. # Don't build any extra formats formats: - - none + - null .. code-block:: yaml @@ -53,16 +54,15 @@ 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 - conda ~~~~~ @@ -71,12 +71,11 @@ 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: @@ -84,7 +83,6 @@ The file option specified the Conda `environment file`_ to use. .. note:: Conda is only supported via the YAML file. - build ~~~~~ @@ -95,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`` @@ -130,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:: @@ -149,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 @@ -163,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 @@ -210,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: From 67fed2957e3e1929faec2f57faec08f8682449fd Mon Sep 17 00:00:00 2001 From: Santos Gallegos Date: Mon, 26 Feb 2018 15:14:35 -0500 Subject: [PATCH 3/6] Indentation --- docs/yaml-config.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/yaml-config.rst b/docs/yaml-config.rst index ee7cb7fbcbb..9f0d41dfc0d 100644 --- a/docs/yaml-config.rst +++ b/docs/yaml-config.rst @@ -61,7 +61,7 @@ The path to your pip requirements file. .. code-block:: yaml - requirements_file: requirements/docs.txt + requirements_file: requirements/docs.txt conda ~~~~~ From 2374e9705486aac5370e13afd145c991864a3f0e Mon Sep 17 00:00:00 2001 From: Santos Gallegos Date: Mon, 26 Feb 2018 15:16:04 -0500 Subject: [PATCH 4/6] Indent --- docs/yaml-config.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/yaml-config.rst b/docs/yaml-config.rst index 9f0d41dfc0d..28c6a118759 100644 --- a/docs/yaml-config.rst +++ b/docs/yaml-config.rst @@ -78,8 +78,8 @@ 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. From 6d45d0b63320ac1376bd0480f6d0dc9d9e339308 Mon Sep 17 00:00:00 2001 From: Santos Gallegos Date: Tue, 6 Mar 2018 13:06:24 -0500 Subject: [PATCH 5/6] Updat docs about formats to allow to use [] --- docs/yaml-config.rst | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/docs/yaml-config.rst b/docs/yaml-config.rst index 28c6a118759..1ea30bf4c89 100644 --- a/docs/yaml-config.rst +++ b/docs/yaml-config.rst @@ -29,11 +29,11 @@ formats ~~~~~~~ * Default: ``htmlzip``, ``pdf``, ``epub`` -* Options: ``htmlzip``, ``pdf``, ``epub``, ``null`` +* Options: ``htmlzip``, ``pdf``, ``epub`` * Type: List of options or ``null`` The formats of your documentation you want to be built. -Choose ``null`` to build none of the formats. +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. @@ -41,8 +41,7 @@ Choose ``null`` to build none of the formats. .. code-block:: yaml # Don't build any extra formats - formats: - - null + formats: [] .. code-block:: yaml From 2fb5382a2a5793d45812f5d6e7d6e2332c5fe866 Mon Sep 17 00:00:00 2001 From: Santos Gallegos Date: Mon, 7 May 2018 16:11:21 -0500 Subject: [PATCH 6/6] Update formats spec --- docs/yaml-config.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/yaml-config.rst b/docs/yaml-config.rst index d58199d9dc8..3438f71e54c 100644 --- a/docs/yaml-config.rst +++ b/docs/yaml-config.rst @@ -30,9 +30,9 @@ Supported settings formats ~~~~~~~ -* Default: ``htmlzip``, ``pdf``, ``epub`` +* Default: [``htmlzip``, ``pdf``, ``epub``] * Options: ``htmlzip``, ``pdf``, ``epub`` -* Type: List of options or ``null`` +* Type: List The formats of your documentation you want to be built. Set as an empty list ``[]`` to build none of the formats.