From 76af98a082c32ad58cf7edd9c2b9612ddbc1bc5a Mon Sep 17 00:00:00 2001 From: Santos Gallegos Date: Thu, 19 Jul 2018 17:20:54 -0500 Subject: [PATCH 01/47] Rename docs from v1 --- docs/{yaml-config.rst => config-file/v1.rst} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename docs/{yaml-config.rst => config-file/v1.rst} (100%) diff --git a/docs/yaml-config.rst b/docs/config-file/v1.rst similarity index 100% rename from docs/yaml-config.rst rename to docs/config-file/v1.rst From d09b3c252c4b27a724465e0823b49f99c202cdf3 Mon Sep 17 00:00:00 2001 From: Santos Gallegos Date: Mon, 30 Jul 2018 15:15:53 -0500 Subject: [PATCH 02/47] Add docs for v2 --- docs/config-file/index.rst | 22 +++ docs/config-file/v1.rst | 18 +- docs/config-file/v2.rst | 357 +++++++++++++++++++++++++++++++++++++ docs/index.rst | 2 +- 4 files changed, 394 insertions(+), 5 deletions(-) create mode 100644 docs/config-file/index.rst create mode 100644 docs/config-file/v2.rst diff --git a/docs/config-file/index.rst b/docs/config-file/index.rst new file mode 100644 index 00000000000..002785cb549 --- /dev/null +++ b/docs/config-file/index.rst @@ -0,0 +1,22 @@ +Configuration File +================== + +Additionally to the admin panel of your project, +you can use a configuration file in the root of your project. +The main advantages of using a configuration file over the web interface are: + +- Some settings are only avaliable using a configuration file +- The settings are per version rather than per project. +- The settings live in your VCS. + +.. note:: + + Using a configuration file is the recomended way of using Read the Docs, + the web interface would be deprecated, + old projects would be able to keep using the web interface. + +.. toctree:: + :maxdepth: 3 + + Version 2 + Version 1 diff --git a/docs/config-file/v1.rst b/docs/config-file/v1.rst index 721c85bb9c1..af3cc7e598a 100644 --- a/docs/config-file/v1.rst +++ b/docs/config-file/v1.rst @@ -1,12 +1,13 @@ -Read the Docs YAML Config -========================= +Configuration File V1 +===================== Read the Docs now has support for configuring builds with a YAML file. The file, ``readthedocs.yml``, must be in the root directory of your project. -.. warning:: This feature is in a beta state. - Please file an `issue`_ if you find anything wrong. +.. note:: + The version 2 of the configuration file is now avaliable. + See the :doc:`new features and how to migrate from v1 `. Here is an example of what this file looks like: @@ -25,6 +26,15 @@ Here is an example of what this file looks like: Supported settings ------------------ +version +~~~~~~~ + +* Default: 1 + +.. code-block:: yaml + + version: 1 + .. _yaml__formats: formats diff --git a/docs/config-file/v2.rst b/docs/config-file/v2.rst new file mode 100644 index 00000000000..b7fd377c619 --- /dev/null +++ b/docs/config-file/v2.rst @@ -0,0 +1,357 @@ +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 ` 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 `_ +section to install in addition to the `package 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 `_: 2, 2.7, 3, 3.3, 3.4, 3.5, 3.6 +* `latest `_: 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. + +* Type: ``path`` +* Default: ``null`` + +If the value is ``null``, +Read the Docs would try to find a ``conf.py`` file in your project. + +sphinx.fail_on_warning +`````````````````````` + +Turn warnings into errors. +This means that the build stops at the first warning and exits with exit status 1. + +* Type: ``bool`` +* Default: ``false`` + +mkdocs +~~~~~~ + +Configuration for Mkdocs documentation. + +.. code-block:: yaml + + mkdocs: + configuration: mkdocs.yml + fail_on_warning: false + +mkdocs.configuration +```````````````````` + +The path to the ``mkdocs.yml`` file + +* Type: ``path`` +* Default: ``null`` + +If the value is ``null``, +Read the Docs would try to find a ``mkdocs.yml`` file in your project. + +mkdocs.fail_on_warning +`````````````````````` + +Turn warnings into errors. +This means that the build stops at the first warning and exits with exit status 1. + +* Type: ``bool`` +* Default: ``false`` + +submodules +~~~~~~~~~~ + +Git submodules configuration. + +.. note:: + + You can't include and exclude submodules at the same time. + +.. code-block:: yaml + + submodules: + include: all + recursive: true + +submodules.include +`````````````````` + +List of submodules to be included. + +* Type: ``list`` +* Default: ``[]`` + +.. note:: + + You can use the ``all`` keyword to include all submodules. + + .. code-block:: yaml + + submodules: + include: all + +submodules.exclude +`````````````````` + +List of submodules to be excluded. + +* Type: ``list`` +* Default: ``[]`` + +.. note:: + + You can use the ``all`` keyword to exclude all submodules. + This is the same as ``include: []``. + + .. code-block:: yaml + + submodules: + exclude: all + +submodules.recursive +```````````````````` + +Do a recursive clone of the submodules. + +* Type: ``bool`` +* Default: ``false`` + +Schema +------ + +You can see the complete schema +`here `_. + +Migrating from v1 +----------------- + +- First, make sure to add the :ref:`version setting `. + +Changes +~~~~~~~ + +- The default value of the :ref:`config-file/v2:formats` setting has change to ``[]`` + and it doesn't include the values from the web interface. +- The top setting ``requirements_file`` was moved to ``python.requirements``. + And it accepts the ``''`` (empty string) value to completely ignore finding a requirements file. + See :ref:`config-file/v2:python.requirements`. +- The setting `conda.file` was renamed to ``conda.environment``. + See :ref:`config-file/v2:conda.environment`. +- The ``build.image`` setting now only has two options: ``latest`` (default) and ``stable``. + See :ref:`config-file/v2:build.image`. +- The settings ``python.setup_py_install`` and ``python.pip_install`` were replaced by ``python.install``. + The previous setting is the same as ``python.install: setup.py`` or ``python.install: pip``. + See :ref:`config-file/v2:python.install`. +- The setting ``python.use_system_site_packages`` was renamed to ``python.system_packages``. + See :ref:`config-file/v2:python.system_packages`. + +.. warning:: + + Some values from the web interface are no longer respected, + please see :ref:`config-file/v2:Migrating from web interface` if you have settings there. + +New +~~~ + +- :ref:`config-file/v2:sphinx` +- :ref:`config-file/v2:mkdocs` +- :ref:`config-file/v2:submodules` + +Migrating from the web interface +-------------------------------- + +This should be pretty straightforward, +just go to the admin panel of your project, +advanced settings and find their respective setting :ref:`here `. + +.. note:: + + Not all settings in the web interface are per version, but per project. + Those settings aren't supported via the configuration file (like ``Default branch``). diff --git a/docs/index.rst b/docs/index.rst index 7f3d2307e17..43fb5355264 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -61,7 +61,7 @@ to help you create fantastic documentation for your project. connected-accounts support faq - yaml-config + config-file/index guides/index api/index embed From 61eff391f2cce6aa98e660d4ec083d07d8336336 Mon Sep 17 00:00:00 2001 From: Santos Gallegos Date: Mon, 30 Jul 2018 15:32:51 -0500 Subject: [PATCH 03/47] Add docs for sphinx.buider --- docs/config-file/v2.rst | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs/config-file/v2.rst b/docs/config-file/v2.rst index b7fd377c619..2dcb27ba93a 100644 --- a/docs/config-file/v2.rst +++ b/docs/config-file/v2.rst @@ -194,6 +194,12 @@ Configuration for Sphinx documentation sphinx.builder `````````````` +The builder type for the Sphinx documentation. + +* Type: ``string`` +* Options: ``html``, ``htmldir``, ``singlehtml`` +* Default: ``html`` + sphinx.configuration ```````````````````` From b2823be5b371877e23d0988a026fb97ffb6e89de Mon Sep 17 00:00:00 2001 From: Santos Gallegos Date: Mon, 30 Jul 2018 19:36:06 -0500 Subject: [PATCH 04/47] Typos --- docs/config-file/index.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/config-file/index.rst b/docs/config-file/index.rst index 002785cb549..4c5fe0008b7 100644 --- a/docs/config-file/index.rst +++ b/docs/config-file/index.rst @@ -5,13 +5,13 @@ Additionally to the admin panel of your project, you can use a configuration file in the root of your project. The main advantages of using a configuration file over the web interface are: -- Some settings are only avaliable using a configuration file +- Some settings are only available using a configuration file - The settings are per version rather than per project. - The settings live in your VCS. .. note:: - Using a configuration file is the recomended way of using Read the Docs, + Using a configuration file is the recommended way of using Read the Docs, the web interface would be deprecated, old projects would be able to keep using the web interface. From 3d61b5c7776b720febb834923e57ff030fc74a4c Mon Sep 17 00:00:00 2001 From: Santos Gallegos Date: Mon, 30 Jul 2018 20:05:54 -0500 Subject: [PATCH 05/47] Use same name --- docs/config-file/v1.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/config-file/v1.rst b/docs/config-file/v1.rst index af3cc7e598a..f89fbb4ab6c 100644 --- a/docs/config-file/v1.rst +++ b/docs/config-file/v1.rst @@ -2,7 +2,7 @@ Configuration File V1 ===================== Read the Docs now has support for configuring builds with a YAML file. -The file, ``readthedocs.yml``, must be in the root directory of your project. +The file, ``.readthedocs.yml``, must be in the root directory of your project. .. note:: From 702ee70bfc3d1074b4c3120015f68520882f9943 Mon Sep 17 00:00:00 2001 From: Santos Gallegos Date: Mon, 30 Jul 2018 20:06:10 -0500 Subject: [PATCH 06/47] List all filenames in index --- docs/config-file/index.rst | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/docs/config-file/index.rst b/docs/config-file/index.rst index 4c5fe0008b7..d95ed555614 100644 --- a/docs/config-file/index.rst +++ b/docs/config-file/index.rst @@ -3,6 +3,13 @@ Configuration File Additionally to the admin panel of your project, you can use a configuration file in the root of your project. +The configuration file can be named as: + +- ``readthedocs.yml`` +- ``readthedocs.yaml`` +- ``.readthedocs.yml`` +- ``.readthedocs.yaml`` + The main advantages of using a configuration file over the web interface are: - Some settings are only available using a configuration file From 1a840acdd81e4de027aca8578e5cc85e1a66d798 Mon Sep 17 00:00:00 2001 From: Santos Gallegos Date: Mon, 30 Jul 2018 20:28:27 -0500 Subject: [PATCH 07/47] Fix ref --- docs/config-file/v2.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/config-file/v2.rst b/docs/config-file/v2.rst index 2dcb27ba93a..177aa4fc385 100644 --- a/docs/config-file/v2.rst +++ b/docs/config-file/v2.rst @@ -341,7 +341,7 @@ Changes .. warning:: Some values from the web interface are no longer respected, - please see :ref:`config-file/v2:Migrating from web interface` if you have settings there. + please see :ref:`config-file/v2:Migrating from the web interface` if you have settings there. New ~~~ From f50b033e9555861e300d147b4133e4b6c637cfe1 Mon Sep 17 00:00:00 2001 From: Santos Gallegos Date: Thu, 2 Aug 2018 13:52:28 -0500 Subject: [PATCH 08/47] Better sentence --- docs/config-file/index.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/config-file/index.rst b/docs/config-file/index.rst index d95ed555614..cbaecbf9b1b 100644 --- a/docs/config-file/index.rst +++ b/docs/config-file/index.rst @@ -1,7 +1,7 @@ Configuration File ================== -Additionally to the admin panel of your project, +In addition to using the admin panel of your project to configure your project, you can use a configuration file in the root of your project. The configuration file can be named as: From 8b67757c202a75769c4956d0cc4ef6c4a5fecace Mon Sep 17 00:00:00 2001 From: Santos Gallegos Date: Thu, 2 Aug 2018 13:52:42 -0500 Subject: [PATCH 09/47] Don't mention the deprecation yet --- docs/config-file/index.rst | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/docs/config-file/index.rst b/docs/config-file/index.rst index cbaecbf9b1b..1356ba00037 100644 --- a/docs/config-file/index.rst +++ b/docs/config-file/index.rst @@ -18,9 +18,7 @@ The main advantages of using a configuration file over the web interface are: .. note:: - Using a configuration file is the recommended way of using Read the Docs, - the web interface would be deprecated, - old projects would be able to keep using the web interface. + Using a configuration file is the recommended way of using Read the Docs. .. toctree:: :maxdepth: 3 From aa9455dd2873f40730495d0ac3fd64a9155b544a Mon Sep 17 00:00:00 2001 From: Santos Gallegos Date: Thu, 2 Aug 2018 13:58:18 -0500 Subject: [PATCH 10/47] Link the filename to just one place --- docs/config-file/v1.rst | 2 +- docs/config-file/v2.rst | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/config-file/v1.rst b/docs/config-file/v1.rst index f89fbb4ab6c..93f5e087d53 100644 --- a/docs/config-file/v1.rst +++ b/docs/config-file/v1.rst @@ -2,7 +2,7 @@ Configuration File V1 ===================== Read the Docs now has support for configuring builds with a YAML file. -The file, ``.readthedocs.yml``, must be in the root directory of your project. +:doc:`The Read the Docs file ` must be in the root directory of your project. .. note:: diff --git a/docs/config-file/v2.rst b/docs/config-file/v2.rst index 177aa4fc385..aed088c3edd 100644 --- a/docs/config-file/v2.rst +++ b/docs/config-file/v2.rst @@ -1,8 +1,8 @@ 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. +Read the Docs support configuring your documentation builds with a YAML file. +:doc:`The Read the Docs file ` must be in the root directory of your project. Here is an example of how this file looks like: From a4544d9bfaae03a62cba38e850b861d7fcf62b2c Mon Sep 17 00:00:00 2001 From: Santos Gallegos Date: Thu, 2 Aug 2018 14:24:18 -0500 Subject: [PATCH 11/47] Change bullet list to definition list --- docs/config-file/v2.rst | 74 +++++++++++++++++++++-------------------- 1 file changed, 38 insertions(+), 36 deletions(-) diff --git a/docs/config-file/v2.rst b/docs/config-file/v2.rst index aed088c3edd..dcab6da89f5 100644 --- a/docs/config-file/v2.rst +++ b/docs/config-file/v2.rst @@ -22,7 +22,7 @@ Supported settings version ~~~~~~~ -* Required +:Required: ``true`` .. code-block:: yaml @@ -37,9 +37,9 @@ formats Formats of the documentation to be built. -* Type: ``list`` -* Options: ``htmlzip``, ``pdf``, ``epub`` -* Default: ``[]`` +:Type: ``list`` +:Options: ``htmlzip``, ``pdf``, ``epub`` +:Default: ``[]`` .. code-block:: yaml @@ -82,16 +82,16 @@ python.version The Python version (this depends on :ref:`config-file/v2:build.image`). -* Type: ``number`` -* Default: ``3`` +:Type: ``number`` +:Default: ``3`` python.requirements ``````````````````` The path to the requirements file from the root of the project. -* Type: ``path`` -* Default: ``null`` +: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. @@ -102,9 +102,11 @@ python.install Install the project using python ``python setup.py install`` or ``pip install .``. -* Type: ``string`` -* Options: ``pip``, ``setup.py`` -* Default: ``null`` +:Type: ``string`` +:Options: ``pip``, ``setup.py`` +:Default: ``null`` + +If the value is ``null``, Read the Docs would not install your project. python.extra_requirements ````````````````````````` @@ -112,8 +114,8 @@ python.extra_requirements `Extra requirements `_ section to install in addition to the `package dependencies `_. -* Type: ``list`` -* Default: ``[]`` +:Type: ``list`` +:Default: ``[]`` .. warning:: @@ -129,8 +131,8 @@ python.system_packages Give the virtual environment access to the global site-packages directory. -* Type: ``bool`` -* Default: ``false`` +:Type: ``bool`` +:Default: ``false`` conda ~~~~~ @@ -147,8 +149,8 @@ conda.environment The path to the Conda environment file from the root of the project. -* Type: ``path`` -* Required +:Type: ``path`` +:Required: ``true`` build ~~~~~ @@ -169,8 +171,8 @@ build.image The build Docker image to be used. -* Type: ``string`` -* Options: ``stable``, ``latest`` +:Type: ``string`` +:Options: ``stable``, ``latest`` Each image support different Python versions and has different packages installed, as defined here: @@ -196,17 +198,17 @@ sphinx.builder The builder type for the Sphinx documentation. -* Type: ``string`` -* Options: ``html``, ``htmldir``, ``singlehtml`` -* Default: ``html`` +:Type: ``string`` +:Options: ``html``, ``htmldir``, ``singlehtml`` +:Default: ``html`` sphinx.configuration ```````````````````` The path to the ``conf.py`` file. -* Type: ``path`` -* Default: ``null`` +:Type: ``path`` +:Default: ``null`` If the value is ``null``, Read the Docs would try to find a ``conf.py`` file in your project. @@ -217,8 +219,8 @@ sphinx.fail_on_warning Turn warnings into errors. This means that the build stops at the first warning and exits with exit status 1. -* Type: ``bool`` -* Default: ``false`` +:Type: ``bool`` +:Default: ``false`` mkdocs ~~~~~~ @@ -236,8 +238,8 @@ mkdocs.configuration The path to the ``mkdocs.yml`` file -* Type: ``path`` -* Default: ``null`` +:Type: ``path`` +:Default: ``null`` If the value is ``null``, Read the Docs would try to find a ``mkdocs.yml`` file in your project. @@ -248,8 +250,8 @@ mkdocs.fail_on_warning Turn warnings into errors. This means that the build stops at the first warning and exits with exit status 1. -* Type: ``bool`` -* Default: ``false`` +:Type: ``bool`` +:Default: ``false`` submodules ~~~~~~~~~~ @@ -271,8 +273,8 @@ submodules.include List of submodules to be included. -* Type: ``list`` -* Default: ``[]`` +:Type: ``list`` +:Default: ``[]`` .. note:: @@ -288,8 +290,8 @@ submodules.exclude List of submodules to be excluded. -* Type: ``list`` -* Default: ``[]`` +:Type: ``list`` +:Default: ``[]`` .. note:: @@ -306,8 +308,8 @@ submodules.recursive Do a recursive clone of the submodules. -* Type: ``bool`` -* Default: ``false`` +:Type: ``bool`` +:Default: ``false`` Schema ------ From c1f34a990905fad1ad98acf72ac95b9ffa9cac8a Mon Sep 17 00:00:00 2001 From: Santos Gallegos Date: Thu, 2 Aug 2018 14:27:49 -0500 Subject: [PATCH 12/47] Typo --- docs/config-file/v2.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/config-file/v2.rst b/docs/config-file/v2.rst index dcab6da89f5..50e97a7aaca 100644 --- a/docs/config-file/v2.rst +++ b/docs/config-file/v2.rst @@ -361,5 +361,5 @@ advanced settings and find their respective setting :ref:`here Date: Thu, 2 Aug 2018 21:13:27 -0500 Subject: [PATCH 13/47] Typo --- docs/config-file/v2.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/config-file/v2.rst b/docs/config-file/v2.rst index 50e97a7aaca..a2bd9dcf99b 100644 --- a/docs/config-file/v2.rst +++ b/docs/config-file/v2.rst @@ -1,7 +1,7 @@ Configuration File V2 ===================== -Read the Docs support configuring your documentation builds with a YAML file. +Read the Docs supports configuring your documentation builds with a YAML file. :doc:`The Read the Docs file ` must be in the root directory of your project. Here is an example of how this file looks like: From 8273f7429bc68a1590e894507a5ab277cc001d55 Mon Sep 17 00:00:00 2001 From: Santos Gallegos Date: Thu, 2 Aug 2018 21:15:28 -0500 Subject: [PATCH 14/47] Point to correct docker version for stable --- docs/config-file/v2.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/config-file/v2.rst b/docs/config-file/v2.rst index a2bd9dcf99b..6229f04e662 100644 --- a/docs/config-file/v2.rst +++ b/docs/config-file/v2.rst @@ -177,7 +177,7 @@ The build Docker image to be used. Each image support different Python versions and has different packages installed, as defined here: -* `stable `_: 2, 2.7, 3, 3.3, 3.4, 3.5, 3.6 +* `stable `_: 2, 2.7, 3, 3.3, 3.4, 3.5, 3.6 * `latest `_: 2, 2.7, 3, 3.3, 3.4, 3.5, 3.6 sphinx From 233eb9265c0b79a3080484210bc6c99334c55ccf Mon Sep 17 00:00:00 2001 From: Santos Gallegos Date: Mon, 6 Aug 2018 14:46:41 -0500 Subject: [PATCH 15/47] Add supportedversions role --- docs/.rstcheck.cfg | 2 +- docs/config-file/v2.rst | 4 ++-- docs/doc_extensions.py | 34 ++++++++++++++++++++++++++++++++-- 3 files changed, 35 insertions(+), 5 deletions(-) diff --git a/docs/.rstcheck.cfg b/docs/.rstcheck.cfg index 1b093d3f696..0bf4df183e4 100644 --- a/docs/.rstcheck.cfg +++ b/docs/.rstcheck.cfg @@ -1,4 +1,4 @@ [rstcheck] ignore_directives=automodule,http:get,tabs,tab -ignore_roles=djangosetting,setting +ignore_roles=djangosetting,setting,supportedversions ignore_messages=(Duplicate implicit target name: ".*")|(Hyperlink target ".*" is not referenced) diff --git a/docs/config-file/v2.rst b/docs/config-file/v2.rst index 6229f04e662..02ca08e569a 100644 --- a/docs/config-file/v2.rst +++ b/docs/config-file/v2.rst @@ -177,8 +177,8 @@ The build Docker image to be used. Each image support different Python versions and has different packages installed, as defined here: -* `stable `_: 2, 2.7, 3, 3.3, 3.4, 3.5, 3.6 -* `latest `_: 2, 2.7, 3, 3.3, 3.4, 3.5, 3.6 +* `stable `_: :supportedversions:`2.0` +* `latest `_: :supportedversions:`3.0` sphinx ~~~~~~ diff --git a/docs/doc_extensions.py b/docs/doc_extensions.py index ae65d8e4221..e3635496670 100644 --- a/docs/doc_extensions.py +++ b/docs/doc_extensions.py @@ -6,11 +6,19 @@ djangosetting Output an inline literal of the corresponding setting value. Useful for keeping documentation up to date without editing on settings changes. + +supportedversions + Output a comma separated list of the supported python versions for a + Read the Docs build image. """ -from docutils import nodes, utils +from __future__ import division, print_function, unicode_literals from django.conf import settings +from docutils import nodes, utils + +from readthedocs.config.config import ( + DOCKER_DEFAULT_IMAGE, DOCKER_IMAGE_SETTINGS) def django_setting_role(typ, rawtext, text, lineno, inliner, options=None, @@ -21,9 +29,31 @@ def django_setting_role(typ, rawtext, text, lineno, inliner, options=None, return [node], [] +def python_supported_versions_role(typ, rawtext, text, lineno, inliner, + options=None, content=None): + """Up to date supported python versions for each build image.""" + image = '{}:{}'.format(DOCKER_DEFAULT_IMAGE, text) + image_settings = DOCKER_IMAGE_SETTINGS[image] + python_versions = image_settings['python']['supported_versions'] + node_list = [] + separator = ', ' + for i, version in enumerate(python_versions): + node_list.append(nodes.literal(version, version)) + if i < len(python_versions) - 1: + node_list.append(nodes.Text(separator)) + return (node_list, []) + + def setup(_): from docutils.parsers.rst import roles - roles.register_local_role('djangosetting', django_setting_role) + roles.register_local_role( + 'djangosetting', + django_setting_role + ) + roles.register_local_role( + 'supportedversions', + python_supported_versions_role + ) return { 'version': 'builtin', From 358737b56e57ac37e3e97e093ea7d4f6a193c539 Mon Sep 17 00:00:00 2001 From: Santos Gallegos Date: Mon, 6 Aug 2018 14:57:52 -0500 Subject: [PATCH 16/47] Fix old links to yaml-config --- docs/conda.rst | 9 +-------- docs/gsoc.rst | 2 +- docs/guides/build-using-too-many-resources.rst | 3 ++- 3 files changed, 4 insertions(+), 10 deletions(-) diff --git a/docs/conda.rst b/docs/conda.rst index 27d00725c2f..f25119711fa 100644 --- a/docs/conda.rst +++ b/docs/conda.rst @@ -14,14 +14,7 @@ This work was funded by `Clinical Graphics`_ -- many thanks for their support of Activating Conda ---------------- -Conda Support is the first feature enabled with :doc:`yaml-config`. -You can enable it by creating a `readthedocs.yml` file in the root of your -repository with the contents: - -.. code-block:: yaml - - conda: - file: environment.yml +Conda support is avalible using a :doc:`config-file/index`. This Conda environment will also have Sphinx and other build time dependencies installed. It will use the same order of operations that we support currently: diff --git a/docs/gsoc.rst b/docs/gsoc.rst index a67f210cf82..c38ce6bbd2d 100644 --- a/docs/gsoc.rst +++ b/docs/gsoc.rst @@ -78,7 +78,7 @@ This project will include: Finish YAML config ~~~~~~~~~~~~~~~~~~ -Currently we have a basic :doc:`/yaml-config` for Read the Docs. +Currently we have a basic :doc:`configuration file ` for Read the Docs. It's still considered beta, and there are a number of features that it doesn't support. We need to support everying users can currently do from our website dashboard inside the YAML file, diff --git a/docs/guides/build-using-too-many-resources.rst b/docs/guides/build-using-too-many-resources.rst index 840d5421d85..c39256c00b4 100644 --- a/docs/guides/build-using-too-many-resources.rst +++ b/docs/guides/build-using-too-many-resources.rst @@ -10,7 +10,8 @@ there are a couple fixes that you might try. Reduce formats you're building ------------------------------ -You can change the formats of docs that you're building with our YAML file's :ref:`yaml-config:Formats` option. +You can change the formats of docs that you're building with our :doc:`/config-file/index` +(search for the `formats` option). In particular, the ``htmlzip`` takes up a decent amount of memory and time, so disabling that format might solve your problem. From 37d582938d0b4234fd97857cd037f59d79c36ae5 Mon Sep 17 00:00:00 2001 From: Santos Gallegos Date: Fri, 10 Aug 2018 12:07:21 -0500 Subject: [PATCH 17/47] Update link to configuration file --- docs/guides/specifying-dependencies.rst | 14 +++----------- 1 file changed, 3 insertions(+), 11 deletions(-) diff --git a/docs/guides/specifying-dependencies.rst b/docs/guides/specifying-dependencies.rst index 0019598a625..2ebf837775a 100644 --- a/docs/guides/specifying-dependencies.rst +++ b/docs/guides/specifying-dependencies.rst @@ -16,18 +16,10 @@ To use the requirements file, create and place the requirements file in the root docs/requirements.txt -Using the YAML configuration file ---------------------------------- - -The recommended approach for specifying a pip requirements file is to use a ``readthedocs.yml`` file. - -The file's path should be relative to documentation root. - -.. code-block:: yaml - - requirements_file: requirements.txt +Using a configuration file +-------------------------- -See :doc:`/yaml-config` for setting up the .yml file +The recommended approach for specifying a pip requirements file is to use a :doc:`/config-file/index` file. Using the project admin dashboard --------------------------------- From 00edff47bac4787be69ddf55de76d30eec560bdb Mon Sep 17 00:00:00 2001 From: Santos Gallegos Date: Fri, 10 Aug 2018 12:17:43 -0500 Subject: [PATCH 18/47] Link to specific conda docs --- docs/guides/specifying-dependencies.rst | 19 +++---------------- 1 file changed, 3 insertions(+), 16 deletions(-) diff --git a/docs/guides/specifying-dependencies.rst b/docs/guides/specifying-dependencies.rst index 2ebf837775a..d59a2d3b465 100644 --- a/docs/guides/specifying-dependencies.rst +++ b/docs/guides/specifying-dependencies.rst @@ -33,22 +33,9 @@ Once the requirements file has been created; Using a conda environment file ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -If using conda, the dependencies can be specified in the conda environment file, ``environment.yml`` . +If using conda, the dependencies can be specified in the `conda environment file`_: ``environment.yml`` . -More on Read the Doc's conda support: :doc:`/conda` - -Working with `conda and environment.yml`_ - -.. note:: Conda is only supported via the YAML file. - -This conda environment file can be specified in ``readthedocs.yml`` in the ``conda`` block. - -.. code-block:: yaml - - conda: - file: environment.yml - -As before, the path should be relative to the documentation repository root. +More on Read the Doc's conda support: :doc:`/conda`. .. _`pip user guide`: https://pip.pypa.io/en/stable/user_guide/#requirements-files -.. _`conda and environment.yml`: https://conda.io/docs/user-guide/tasks/manage-environments.html +.. _`conda environment file`: https://conda.io/docs/user-guide/tasks/manage-environments.html From f2d47f37338fa6ede40bd65cfb1d648655dbbba8 Mon Sep 17 00:00:00 2001 From: Santos Gallegos Date: Wed, 15 Aug 2018 11:32:54 -0500 Subject: [PATCH 19/47] New advatage --- docs/config-file/index.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/config-file/index.rst b/docs/config-file/index.rst index 1356ba00037..1b6e4b8c8c1 100644 --- a/docs/config-file/index.rst +++ b/docs/config-file/index.rst @@ -15,6 +15,7 @@ The main advantages of using a configuration file over the web interface are: - Some settings are only available using a configuration file - The settings are per version rather than per project. - The settings live in your VCS. +- Reproducible build environments over time. .. note:: From 362be88b53dbeef8db4a6d49dee83caf3390d20d Mon Sep 17 00:00:00 2001 From: Santos Gallegos Date: Wed, 15 Aug 2018 11:33:15 -0500 Subject: [PATCH 20/47] Use tip instead of note --- docs/config-file/index.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/config-file/index.rst b/docs/config-file/index.rst index 1b6e4b8c8c1..fabf9bdd580 100644 --- a/docs/config-file/index.rst +++ b/docs/config-file/index.rst @@ -17,7 +17,7 @@ The main advantages of using a configuration file over the web interface are: - The settings live in your VCS. - Reproducible build environments over time. -.. note:: +.. tip:: Using a configuration file is the recommended way of using Read the Docs. From 93a89f2719f33ab1cb5684a6882f6356f9bec45a Mon Sep 17 00:00:00 2001 From: Santos Gallegos Date: Wed, 15 Aug 2018 11:33:44 -0500 Subject: [PATCH 21/47] Update note about using v2 instead of v1 --- docs/config-file/v1.rst | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/config-file/v1.rst b/docs/config-file/v1.rst index 93f5e087d53..1c6294583d0 100644 --- a/docs/config-file/v1.rst +++ b/docs/config-file/v1.rst @@ -4,10 +4,12 @@ Configuration File V1 Read the Docs now has support for configuring builds with a YAML file. :doc:`The Read the Docs file ` must be in the root directory of your project. -.. note:: +.. warning:: + Version 1 shouldn't be used. The version 2 of the configuration file is now avaliable. - See the :doc:`new features and how to migrate from v1 `. + See the :ref:`new features ` + and :ref:`how to migrate from v1 `. Here is an example of what this file looks like: From 239201b81b91ddb689a749ac83807e7b0743cd45 Mon Sep 17 00:00:00 2001 From: Santos Gallegos Date: Wed, 15 Aug 2018 11:34:31 -0500 Subject: [PATCH 22/47] Add example word --- docs/config-file/v2.rst | 13 ++++++++++++- 1 file changed, 12 insertions(+), 1 deletion(-) diff --git a/docs/config-file/v2.rst b/docs/config-file/v2.rst index 02ca08e569a..c8144e08fe6 100644 --- a/docs/config-file/v2.rst +++ b/docs/config-file/v2.rst @@ -24,6 +24,8 @@ version :Required: ``true`` +Example: + .. code-block:: yaml version: 2 @@ -41,6 +43,8 @@ Formats of the documentation to be built. :Options: ``htmlzip``, ``pdf``, ``epub`` :Default: ``[]`` +Example: + .. code-block:: yaml # Default @@ -66,6 +70,7 @@ python ~~~~~~ Configuration of the Python environment to be used. +Example: .. code-block:: yaml @@ -138,6 +143,7 @@ conda ~~~~~ Configuration for Conda support. +Example: .. code-block:: yaml @@ -156,6 +162,7 @@ build ~~~~~ Configuration for the documentation build process. +Example: .. code-block:: yaml @@ -185,6 +192,7 @@ sphinx Configuration for Sphinx documentation (this is the default documentation type). +Example: .. code-block:: yaml @@ -226,6 +234,7 @@ mkdocs ~~~~~~ Configuration for Mkdocs documentation. +Example: .. code-block:: yaml @@ -260,7 +269,9 @@ Git submodules configuration. .. note:: - You can't include and exclude submodules at the same time. + You can't use ``include`` and ``exclude`` settings for submodules at the same time. + +Example: .. code-block:: yaml From 2af7cdf23d0a676bdc9b385790d793f63c8a9b27 Mon Sep 17 00:00:00 2001 From: Santos Gallegos Date: Wed, 15 Aug 2018 11:34:57 -0500 Subject: [PATCH 23/47] Better sentences --- docs/config-file/v2.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/config-file/v2.rst b/docs/config-file/v2.rst index c8144e08fe6..d7b988f3723 100644 --- a/docs/config-file/v2.rst +++ b/docs/config-file/v2.rst @@ -93,7 +93,7 @@ The Python version (this depends on :ref:`config-file/v2:build.image`). python.requirements ``````````````````` -The path to the requirements file from the root of the project. +The path to the requirements file, relative to the root of the project. :Type: ``path`` :Default: ``null`` @@ -127,7 +127,7 @@ section to install in addition to the `package dependencies Date: Wed, 15 Aug 2018 11:35:08 -0500 Subject: [PATCH 24/47] Add default value --- docs/config-file/v2.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/config-file/v2.rst b/docs/config-file/v2.rst index d7b988f3723..6164c2748c1 100644 --- a/docs/config-file/v2.rst +++ b/docs/config-file/v2.rst @@ -180,6 +180,7 @@ The Docker image used for building the docs. :Type: ``string`` :Options: ``stable``, ``latest`` +:Default: ``latest`` Each image support different Python versions and has different packages installed, as defined here: From 8ca9c2ddbb092755537291230a161fcd5812bb08 Mon Sep 17 00:00:00 2001 From: Santos Gallegos Date: Wed, 15 Aug 2018 11:35:27 -0500 Subject: [PATCH 25/47] Link to official docs --- docs/config-file/v2.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/config-file/v2.rst b/docs/config-file/v2.rst index 6164c2748c1..22bdb698cdf 100644 --- a/docs/config-file/v2.rst +++ b/docs/config-file/v2.rst @@ -225,7 +225,7 @@ Read the Docs would try to find a ``conf.py`` file in your project. sphinx.fail_on_warning `````````````````````` -Turn warnings into errors. +`Turn warnings into errors `__. This means that the build stops at the first warning and exits with exit status 1. :Type: ``bool`` @@ -257,7 +257,7 @@ Read the Docs would try to find a ``mkdocs.yml`` file in your project. mkdocs.fail_on_warning `````````````````````` -Turn warnings into errors. +`Turn warnings into errors `__. This means that the build stops at the first warning and exits with exit status 1. :Type: ``bool`` From 2b2a95abca049bac3dcdf1943ae5edecd3707b08 Mon Sep 17 00:00:00 2001 From: Santos Gallegos Date: Wed, 15 Aug 2018 11:35:47 -0500 Subject: [PATCH 26/47] Style --- docs/config-file/v2.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/config-file/v2.rst b/docs/config-file/v2.rst index 22bdb698cdf..866ccd5c1d4 100644 --- a/docs/config-file/v2.rst +++ b/docs/config-file/v2.rst @@ -332,17 +332,17 @@ You can see the complete schema Migrating from v1 ----------------- -- First, make sure to add the :ref:`version setting `. +First, make sure to add the :ref:`version setting `. Changes ~~~~~~~ - The default value of the :ref:`config-file/v2:formats` setting has change to ``[]`` and it doesn't include the values from the web interface. -- The top setting ``requirements_file`` was moved to ``python.requirements``. - And it accepts the ``''`` (empty string) value to completely ignore finding a requirements file. +- The top setting ``requirements_file`` was moved to ``python.requirements`` + and it accepts the ``''`` (empty string) value to completely ignore finding a requirements file. See :ref:`config-file/v2:python.requirements`. -- The setting `conda.file` was renamed to ``conda.environment``. +- The setting ``conda.file`` was renamed to ``conda.environment``. See :ref:`config-file/v2:conda.environment`. - The ``build.image`` setting now only has two options: ``latest`` (default) and ``stable``. See :ref:`config-file/v2:build.image`. From b9f436564d04c1a1b8f807276f453d759b28232e Mon Sep 17 00:00:00 2001 From: Santos Gallegos Date: Wed, 15 Aug 2018 11:40:19 -0500 Subject: [PATCH 27/47] Rename role --- docs/.rstcheck.cfg | 2 +- docs/config-file/v2.rst | 4 ++-- docs/doc_extensions.py | 4 ++-- 3 files changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/.rstcheck.cfg b/docs/.rstcheck.cfg index 0bf4df183e4..acf5168307b 100644 --- a/docs/.rstcheck.cfg +++ b/docs/.rstcheck.cfg @@ -1,4 +1,4 @@ [rstcheck] ignore_directives=automodule,http:get,tabs,tab -ignore_roles=djangosetting,setting,supportedversions +ignore_roles=djangosetting,setting,buildpyversions ignore_messages=(Duplicate implicit target name: ".*")|(Hyperlink target ".*" is not referenced) diff --git a/docs/config-file/v2.rst b/docs/config-file/v2.rst index 866ccd5c1d4..ff1750ea038 100644 --- a/docs/config-file/v2.rst +++ b/docs/config-file/v2.rst @@ -185,8 +185,8 @@ The Docker image used for building the docs. Each image support different Python versions and has different packages installed, as defined here: -* `stable `_: :supportedversions:`2.0` -* `latest `_: :supportedversions:`3.0` +* `stable `_: :buildpyversions:`2.0` +* `latest `_: :buildpyversions:`3.0` sphinx ~~~~~~ diff --git a/docs/doc_extensions.py b/docs/doc_extensions.py index e3635496670..abf387cf049 100644 --- a/docs/doc_extensions.py +++ b/docs/doc_extensions.py @@ -7,7 +7,7 @@ Output an inline literal of the corresponding setting value. Useful for keeping documentation up to date without editing on settings changes. -supportedversions +buildpyversions Output a comma separated list of the supported python versions for a Read the Docs build image. """ @@ -51,7 +51,7 @@ def setup(_): django_setting_role ) roles.register_local_role( - 'supportedversions', + 'buildpyversions', python_supported_versions_role ) From e601db2656107ab5f15c382c65a687d157bab8d3 Mon Sep 17 00:00:00 2001 From: Santos Gallegos Date: Wed, 15 Aug 2018 11:55:10 -0500 Subject: [PATCH 28/47] Include list of global settings --- docs/config-file/v2.rst | 20 ++++++++++++++++---- 1 file changed, 16 insertions(+), 4 deletions(-) diff --git a/docs/config-file/v2.rst b/docs/config-file/v2.rst index ff1750ea038..f9d1d598817 100644 --- a/docs/config-file/v2.rst +++ b/docs/config-file/v2.rst @@ -371,7 +371,19 @@ This should be pretty straightforward, just go to the admin panel of your project, advanced settings and find their respective setting :ref:`here `. -.. note:: - - Not all settings in the web interface are per version, but are per project. - Those settings aren't supported via the configuration file (like ``Default branch``). +Not all settings in the web interface are per version, but are per project. +These settings aren't supported via the configuration file. + +* ``Name`` +* ``Repository URL`` +* ``Repository type`` +* ``Language`` +* ``Programming language`` +* ``Project homepage`` +* ``Tags`` +* ``Single version`` +* ``Default branch`` +* ``Default version`` +* ``Show versions warning`` +* ``Privacy level`` +* ``Analytics code`` From f1d60de0a2fb62960862c63fd0f4206e8d61f1f1 Mon Sep 17 00:00:00 2001 From: Santos Gallegos Date: Thu, 16 Aug 2018 14:01:35 -0500 Subject: [PATCH 29/47] Add note about ignoring submodules.recursive --- docs/config-file/v2.rst | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/config-file/v2.rst b/docs/config-file/v2.rst index f9d1d598817..814840f5157 100644 --- a/docs/config-file/v2.rst +++ b/docs/config-file/v2.rst @@ -323,6 +323,10 @@ Do a recursive clone of the submodules. :Type: ``bool`` :Default: ``false`` +.. note:: + + This is ignored if there aren't submodules to clone. + Schema ------ From 0d6ee5c9cf8b1f90246b37e31df6de8873b0ee5e Mon Sep 17 00:00:00 2001 From: Santos Gallegos Date: Thu, 16 Aug 2018 14:28:07 -0500 Subject: [PATCH 30/47] Link to specific sections --- docs/conda.rst | 3 +-- docs/guides/build-using-too-many-resources.rst | 4 ++-- docs/guides/specifying-dependencies.rst | 3 ++- 3 files changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/conda.rst b/docs/conda.rst index f25119711fa..f4ccc3d0e98 100644 --- a/docs/conda.rst +++ b/docs/conda.rst @@ -14,7 +14,7 @@ This work was funded by `Clinical Graphics`_ -- many thanks for their support of Activating Conda ---------------- -Conda support is avalible using a :doc:`config-file/index`. +Conda support is avalible using a :doc:`config-file/index`, see :ref:`config-file/v2:conda`. This Conda environment will also have Sphinx and other build time dependencies installed. It will use the same order of operations that we support currently: @@ -35,4 +35,3 @@ we can't safely install it as a normal dependency into the normal Python virtual .. _issue: https://github.com/rtfd/readthedocs.org/issues .. _Clinical Graphics: https://www.clinicalgraphics.com/ - diff --git a/docs/guides/build-using-too-many-resources.rst b/docs/guides/build-using-too-many-resources.rst index c39256c00b4..d7ba45cdcd4 100644 --- a/docs/guides/build-using-too-many-resources.rst +++ b/docs/guides/build-using-too-many-resources.rst @@ -10,8 +10,8 @@ there are a couple fixes that you might try. Reduce formats you're building ------------------------------ -You can change the formats of docs that you're building with our :doc:`/config-file/index` -(search for the `formats` option). +You can change the formats of docs that you're building with our :doc:`/config-file/index`, +see :ref:`config-file/v2:formats`. In particular, the ``htmlzip`` takes up a decent amount of memory and time, so disabling that format might solve your problem. diff --git a/docs/guides/specifying-dependencies.rst b/docs/guides/specifying-dependencies.rst index d59a2d3b465..79af79fb045 100644 --- a/docs/guides/specifying-dependencies.rst +++ b/docs/guides/specifying-dependencies.rst @@ -19,7 +19,8 @@ To use the requirements file, create and place the requirements file in the root Using a configuration file -------------------------- -The recommended approach for specifying a pip requirements file is to use a :doc:`/config-file/index` file. +The recommended approach for specifying a pip requirements file is to use a :doc:`/config-file/index` file, +see :ref:`config-file/v2:python.requirements`. Using the project admin dashboard --------------------------------- From c584485b3a935a229231fe3435649f7b9d6ba788 Mon Sep 17 00:00:00 2001 From: Santos Gallegos Date: Wed, 22 Aug 2018 12:05:22 -0500 Subject: [PATCH 31/47] Update link --- docs/builds.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/builds.rst b/docs/builds.rst index c5bdfc2f3ba..4e2accec98b 100644 --- a/docs/builds.rst +++ b/docs/builds.rst @@ -119,7 +119,7 @@ The build environment The build process is executed inside Docker containers, by default the image used is ``readthedocs/build:2.0``, -but you can change that using a :doc:`configuration file `. +but you can change that using a :doc:`config-file/index`. .. note:: From 1f07a174a708e340faff1511219df963c39b4bfa Mon Sep 17 00:00:00 2001 From: Santos Gallegos Date: Wed, 22 Aug 2018 12:07:47 -0500 Subject: [PATCH 32/47] Update link --- docs/guides/build-using-too-many-resources.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guides/build-using-too-many-resources.rst b/docs/guides/build-using-too-many-resources.rst index d7ba45cdcd4..904256c9399 100644 --- a/docs/guides/build-using-too-many-resources.rst +++ b/docs/guides/build-using-too-many-resources.rst @@ -49,6 +49,6 @@ There are a few libraries that Read the Docs has already installed (scipy, numpy in the Docker image used to build your docs. You can check the updated list of pre-installed libraries in the `Docker image repository`_. To use these pre-installed libraries and avoid consuming time re-downloading/compiling them, -you can use the :ref:`yaml-config:python.use_system_site_packages` option to have access to them. +you can use the :ref:`config-file/v2:python.system_packages` option to have access to them. .. _Docker image repository: https://github.com/rtfd/readthedocs-docker-images From 4954238c752d12632042d0d76ef6f45778045e04 Mon Sep 17 00:00:00 2001 From: Santos Gallegos Date: Thu, 30 Aug 2018 12:29:31 -0500 Subject: [PATCH 33/47] Update link --- docs/config-file/v1.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/config-file/v1.rst b/docs/config-file/v1.rst index 1c6294583d0..37ce94ef9fd 100644 --- a/docs/config-file/v1.rst +++ b/docs/config-file/v1.rst @@ -173,7 +173,7 @@ python.use_system_site_packages * Type: Boolean When true, it gives the virtual environment access to the global site-packages directory. -Depending on the :ref:`yaml-config:build.image`, +Depending on the :ref:`config-file/v1:build.image`, Read the Docs includes some libraries like scipy, numpy, etc. See :ref:`builds:The build environment` for more details. From 48b1a4dc688ec65bfb4157c18f7d313ec23e1d1a Mon Sep 17 00:00:00 2001 From: Santos Gallegos Date: Thu, 30 Aug 2018 12:30:45 -0500 Subject: [PATCH 34/47] Ref to build environment --- docs/config-file/v2.rst | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/config-file/v2.rst b/docs/config-file/v2.rst index 814840f5157..0a271fcc631 100644 --- a/docs/config-file/v2.rst +++ b/docs/config-file/v2.rst @@ -139,6 +139,10 @@ Give the virtual environment access to the global site-packages directory. :Type: ``bool`` :Default: ``false`` +Depending on the :ref:`config-file/v2:build.image`, +Read the Docs includes some libraries like scipy, numpy, etc. +See :ref:`builds:The build environment` for more details. + conda ~~~~~ From 9193e07503daa9b35bfa8f30817e85e75faddfa2 Mon Sep 17 00:00:00 2001 From: Santos Gallegos Date: Thu, 4 Oct 2018 11:57:07 -0500 Subject: [PATCH 35/47] Notes about stric validation --- docs/config-file/v2.rst | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/docs/config-file/v2.rst b/docs/config-file/v2.rst index 0a271fcc631..482313fa52d 100644 --- a/docs/config-file/v2.rst +++ b/docs/config-file/v2.rst @@ -19,6 +19,11 @@ Here is an example of how this file looks like: Supported settings ------------------ +.. note:: + + The presence of any other key that isn't documented here will make the build to fail. + This is to avoid common errors. + version ~~~~~~~ @@ -345,7 +350,7 @@ First, make sure to add the :ref:`version setting `. Changes ~~~~~~~ -- The default value of the :ref:`config-file/v2:formats` setting has change to ``[]`` +- The default value of the :ref:`config-file/v2:formats` setting has changed to ``[]`` and it doesn't include the values from the web interface. - The top setting ``requirements_file`` was moved to ``python.requirements`` and it accepts the ``''`` (empty string) value to completely ignore finding a requirements file. @@ -359,6 +364,7 @@ Changes See :ref:`config-file/v2:python.install`. - The setting ``python.use_system_site_packages`` was renamed to ``python.system_packages``. See :ref:`config-file/v2:python.system_packages`. +- The build will fail if there are invalid keys (strict mode). .. warning:: From 90ee8446b5c13fe9a0d9586f65208c1fe8be0487 Mon Sep 17 00:00:00 2001 From: Santos Gallegos Date: Tue, 22 Jan 2019 14:03:37 -0500 Subject: [PATCH 36/47] Update docs to new schema --- docs/config-file/v2.rst | 84 +++++++++++++++++++++++++------------ docs/intro/import-guide.rst | 2 +- 2 files changed, 59 insertions(+), 27 deletions(-) diff --git a/docs/config-file/v2.rst b/docs/config-file/v2.rst index 482313fa52d..1e0a3347a6d 100644 --- a/docs/config-file/v2.rst +++ b/docs/config-file/v2.rst @@ -14,7 +14,9 @@ Here is an example of how this file looks like: python: version: 3.6 - install: pip + install: + - method: pip + path: . Supported settings ------------------ @@ -81,10 +83,13 @@ Example: python: version: 3.6 - requirements: docs/requirements.txt - install: pip - extra_requirements: - - docs + install: + - requirements: docs/requirements.txt + - method: pip + path: . + extra_requirements: docs + - method: setuptools + path: another/package system_packages: true python.version @@ -95,46 +100,73 @@ The Python version (this depends on :ref:`config-file/v2:build.image`). :Type: ``number`` :Default: ``3`` -python.requirements -``````````````````` +python.install +`````````````` + +List of installation of packages and requirements. + +Requirements file +''''''''''''''''' + +Install packages from a requirements file. The path to the requirements file, relative to the root of the project. +:Key: ``requirements`` :Type: ``path`` -:Default: ``null`` +:Required: ``true`` -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 ``''``. +Example: -python.install -`````````````` +.. code-block:: yaml -Install the project using python ``python setup.py install`` or ``pip install .``. + python: + version: 3.6 + install: + - requirements: docs/requirements.txt + - requirements: requirements.txt -:Type: ``string`` -:Options: ``pip``, ``setup.py`` -:Default: ``null`` +Packages +'''''''' + +Install the project using ``python setup.py install`` or ``pip install``. + +The path to the package, relative to the root of the project. + +:Key: ``path`` +:Type: ``path`` +:Required: ``true`` -If the value is ``null``, Read the Docs would not install your project. +The installation method. -python.extra_requirements -````````````````````````` +:Key: ``method`` +:Options: ``pip``, ``setup.py`` +:Default: ``pip`` `Extra requirements `_ section to install in addition to the `package dependencies `_. +.. warning:: + + You need to install your project with ``pip`` to use ``extra_requirements``. + +:Key: ``extra_requirements`` :Type: ``list`` :Default: ``[]`` -.. warning:: - - You need to install your project with ``pip`` to use this feature. - See :ref:`config-file/v2:python.install`. +Example: -Behind the scene the following ``pip`` command will be run:: +.. code-block:: yaml - $ pip install -e .[tests,docs] + python: + version: 3.6 + install: + - method: pip + path: . + extra_requirements: + - docs + - method: setuptools + path: package python.system_packages `````````````````````` diff --git a/docs/intro/import-guide.rst b/docs/intro/import-guide.rst index bc40a948622..3daf18b66f7 100644 --- a/docs/intro/import-guide.rst +++ b/docs/intro/import-guide.rst @@ -59,7 +59,7 @@ and to troubleshoot any issues that arise. Some documentation projects require additional configuration to build such as specifying a certain version of Python or installing additional dependencies. You can configure these settings in a ``readthedocs.yml`` file. -See our :doc:`/yaml-config` docs for more details. +See our :doc:`/config-file/index` docs for more details. Read the Docs will host multiple versions of your code. You can read more about how to use this well on our :doc:`/versions` page. From ebf3b0dd2d4acd51afc30e13eeed4b0a8054d5da Mon Sep 17 00:00:00 2001 From: Santos Gallegos Date: Tue, 22 Jan 2019 14:14:27 -0500 Subject: [PATCH 37/47] Update migration guide --- docs/config-file/v2.rst | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/docs/config-file/v2.rst b/docs/config-file/v2.rst index 1e0a3347a6d..960610c0b8a 100644 --- a/docs/config-file/v2.rst +++ b/docs/config-file/v2.rst @@ -384,16 +384,16 @@ Changes - The default value of the :ref:`config-file/v2:formats` setting has changed to ``[]`` and it doesn't include the values from the web interface. -- The top setting ``requirements_file`` was moved to ``python.requirements`` - and it accepts the ``''`` (empty string) value to completely ignore finding a requirements file. - See :ref:`config-file/v2:python.requirements`. +- The top setting ``requirements_file`` was moved to ``python.install`` + and we don't try to find a requirements file if the option isn't present. + See :ref:`config-file/v2:Requirements file`. - The setting ``conda.file`` was renamed to ``conda.environment``. See :ref:`config-file/v2:conda.environment`. - The ``build.image`` setting now only has two options: ``latest`` (default) and ``stable``. See :ref:`config-file/v2:build.image`. - The settings ``python.setup_py_install`` and ``python.pip_install`` were replaced by ``python.install``. - The previous setting is the same as ``python.install: setup.py`` or ``python.install: pip``. - See :ref:`config-file/v2:python.install`. + And now it accepts a path to the package. + See :ref:`config-file/v2:Packages`. - The setting ``python.use_system_site_packages`` was renamed to ``python.system_packages``. See :ref:`config-file/v2:python.system_packages`. - The build will fail if there are invalid keys (strict mode). @@ -409,6 +409,7 @@ New - :ref:`config-file/v2:sphinx` - :ref:`config-file/v2:mkdocs` - :ref:`config-file/v2:submodules` +- :ref:`config-file/v2:python.install` Migrating from the web interface -------------------------------- From d08283c30af9bf151d52e95861f7727023d5ab25 Mon Sep 17 00:00:00 2001 From: Santos Gallegos Date: Tue, 22 Jan 2019 17:21:38 -0500 Subject: [PATCH 38/47] Reword --- docs/config-file/v2.rst | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/docs/config-file/v2.rst b/docs/config-file/v2.rst index 960610c0b8a..7f5a012a604 100644 --- a/docs/config-file/v2.rst +++ b/docs/config-file/v2.rst @@ -103,7 +103,7 @@ The Python version (this depends on :ref:`config-file/v2:build.image`). python.install `````````````` -List of installation of packages and requirements. +List of installation methods of packages and requirements. Requirements file ''''''''''''''''' @@ -377,11 +377,10 @@ You can see the complete schema Migrating from v1 ----------------- -First, make sure to add the :ref:`version setting `. - Changes ~~~~~~~ +- The version setting is required. See :ref:`config-file/v2:version`. - The default value of the :ref:`config-file/v2:formats` setting has changed to ``[]`` and it doesn't include the values from the web interface. - The top setting ``requirements_file`` was moved to ``python.install`` From b13a5b69157ade60f6134f3631bdf7998373901a Mon Sep 17 00:00:00 2001 From: Santos Gallegos Date: Tue, 22 Jan 2019 17:33:53 -0500 Subject: [PATCH 39/47] Fix link --- docs/guides/specifying-dependencies.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guides/specifying-dependencies.rst b/docs/guides/specifying-dependencies.rst index cfd76c8aa0b..38acb0cd2e7 100644 --- a/docs/guides/specifying-dependencies.rst +++ b/docs/guides/specifying-dependencies.rst @@ -20,7 +20,7 @@ Using a configuration file -------------------------- The recommended approach for specifying a pip requirements file is to use a :doc:`/config-file/index` file, -see :ref:`config-file/v2:python.requirements`. +see :ref:`config-file/v2:Requirements file`. Using the project admin dashboard --------------------------------- From d6c9e40341b700360164b4f8673dc991e5fc61b5 Mon Sep 17 00:00:00 2001 From: Santos Gallegos Date: Tue, 22 Jan 2019 17:47:21 -0500 Subject: [PATCH 40/47] Update extension --- docs/doc_extensions.py | 7 ++----- 1 file changed, 2 insertions(+), 5 deletions(-) diff --git a/docs/doc_extensions.py b/docs/doc_extensions.py index abf387cf049..b318ab973a6 100644 --- a/docs/doc_extensions.py +++ b/docs/doc_extensions.py @@ -17,9 +17,6 @@ from django.conf import settings from docutils import nodes, utils -from readthedocs.config.config import ( - DOCKER_DEFAULT_IMAGE, DOCKER_IMAGE_SETTINGS) - def django_setting_role(typ, rawtext, text, lineno, inliner, options=None, content=None): @@ -32,8 +29,8 @@ def django_setting_role(typ, rawtext, text, lineno, inliner, options=None, def python_supported_versions_role(typ, rawtext, text, lineno, inliner, options=None, content=None): """Up to date supported python versions for each build image.""" - image = '{}:{}'.format(DOCKER_DEFAULT_IMAGE, text) - image_settings = DOCKER_IMAGE_SETTINGS[image] + image = '{}:{}'.format(settings.DOCKER_DEFAULT_IMAGE, text) + image_settings = settings.DOCKER_IMAGE_SETTINGS[image] python_versions = image_settings['python']['supported_versions'] node_list = [] separator = ', ' From c512420a08b95e592ca2c21765ea5cb78b0b9820 Mon Sep 17 00:00:00 2001 From: Santos Gallegos Date: Tue, 22 Jan 2019 17:57:49 -0500 Subject: [PATCH 41/47] Clean up --- docs/config-file/v2.rst | 2 +- docs/doc_extensions.py | 2 -- 2 files changed, 1 insertion(+), 3 deletions(-) diff --git a/docs/config-file/v2.rst b/docs/config-file/v2.rst index 7f5a012a604..46e588c876b 100644 --- a/docs/config-file/v2.rst +++ b/docs/config-file/v2.rst @@ -178,7 +178,7 @@ Give the virtual environment access to the global site-packages directory. Depending on the :ref:`config-file/v2:build.image`, Read the Docs includes some libraries like scipy, numpy, etc. -See :ref:`builds:The build environment` for more details. +See :ref:`builds:The build environment` for more details. conda ~~~~~ diff --git a/docs/doc_extensions.py b/docs/doc_extensions.py index b318ab973a6..60e20b30e6a 100644 --- a/docs/doc_extensions.py +++ b/docs/doc_extensions.py @@ -12,8 +12,6 @@ Read the Docs build image. """ -from __future__ import division, print_function, unicode_literals - from django.conf import settings from docutils import nodes, utils From 9fe4a1dc15205b22b554094d255ef63c4b8906df Mon Sep 17 00:00:00 2001 From: Eric Holscher <25510+ericholscher@users.noreply.github.com> Date: Wed, 23 Jan 2019 11:15:03 -0500 Subject: [PATCH 42/47] Update docs/config-file/v2.rst Co-Authored-By: stsewd --- docs/config-file/v2.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/config-file/v2.rst b/docs/config-file/v2.rst index 46e588c876b..c14a702c649 100644 --- a/docs/config-file/v2.rst +++ b/docs/config-file/v2.rst @@ -24,7 +24,7 @@ Supported settings .. note:: The presence of any other key that isn't documented here will make the build to fail. - This is to avoid common errors. + This is to avoid typos and provide feedback on invalid configurations. version ~~~~~~~ From f5d3ec4f4aa272b53ffa32462c2eadd60e8b9a2d Mon Sep 17 00:00:00 2001 From: Santos Gallegos Date: Wed, 23 Jan 2019 12:08:58 -0500 Subject: [PATCH 43/47] Feedback --- docs/config-file/v2.rst | 42 ++++++++++++++++++++++++++--------------- 1 file changed, 27 insertions(+), 15 deletions(-) diff --git a/docs/config-file/v2.rst b/docs/config-file/v2.rst index c14a702c649..0566c19b8d3 100644 --- a/docs/config-file/v2.rst +++ b/docs/config-file/v2.rst @@ -39,7 +39,7 @@ Example: .. warning:: - If you don't provide the version, :doc:`v1 ` would be used. + If you don't provide the version, :doc:`v1 ` will be used. formats ~~~~~~~ @@ -140,11 +140,13 @@ The path to the package, relative to the root of the project. The installation method. :Key: ``method`` -:Options: ``pip``, ``setup.py`` +:Options: ``pip``, ``setuptools`` :Default: ``pip`` -`Extra requirements `_ -section to install in addition to the `package dependencies `_. +`Extra requirements`_ section to install in addition to the `package dependencies`_. + +.. _Extra Requirements: https://setuptools.readthedocs.io/en/latest/setuptools.html#declaring-extras-optional-features-with-their-own-dependencies +.. _package dependencies: https://setuptools.readthedocs.io/en/latest/setuptools.html#declaring-dependencies .. warning:: @@ -168,6 +170,13 @@ Example: - method: setuptools path: package +With the previous settings, Read the Docs will execute the next commands: + +.. prompt:: bash $ + + pip install .[docs] + python package/setup.py install + python.system_packages `````````````````````` @@ -178,6 +187,7 @@ Give the virtual environment access to the global site-packages directory. Depending on the :ref:`config-file/v2:build.image`, Read the Docs includes some libraries like scipy, numpy, etc. +That you can access to them by enabling this option. See :ref:`builds:The build environment` for more details. conda @@ -194,7 +204,7 @@ Example: conda.environment ````````````````` -The path to the Conda environment file from the root of the project. +The path to the Conda environment file, relative to the root of the project. :Type: ``path`` :Required: ``true`` @@ -226,8 +236,8 @@ The Docker image used for building the docs. Each image support different Python versions and has different packages installed, as defined here: -* `stable `_: :buildpyversions:`2.0` -* `latest `_: :buildpyversions:`3.0` +* `stable `_: :buildpyversions:`2.0` +* `latest `_: :buildpyversions:`3.0` sphinx ~~~~~~ @@ -261,7 +271,7 @@ The path to the ``conf.py`` file, relative to the root of the project. :Default: ``null`` If the value is ``null``, -Read the Docs would try to find a ``conf.py`` file in your project. +Read the Docs will try to find a ``conf.py`` file in your project. sphinx.fail_on_warning `````````````````````` @@ -287,13 +297,13 @@ Example: mkdocs.configuration ```````````````````` -The path to the ``mkdocs.yml`` file +The path to the ``mkdocs.yml`` file, relative to the root of the project. :Type: ``path`` :Default: ``null`` If the value is ``null``, -Read the Docs would try to find a ``mkdocs.yml`` file in your project. +Read the Docs will try to find a ``mkdocs.yml`` file in your project. mkdocs.fail_on_warning `````````````````````` @@ -318,7 +328,9 @@ Example: .. code-block:: yaml submodules: - include: all + include: + - one + - two recursive: true submodules.include @@ -402,8 +414,8 @@ Changes Some values from the web interface are no longer respected, please see :ref:`config-file/v2:Migrating from the web interface` if you have settings there. -New -~~~ +New settings +~~~~~~~~~~~~ - :ref:`config-file/v2:sphinx` - :ref:`config-file/v2:mkdocs` @@ -414,8 +426,8 @@ Migrating from the web interface -------------------------------- This should be pretty straightforward, -just go to the admin panel of your project, -advanced settings and find their respective setting :ref:`here `. +just go to the :guilabel:`Admin` > :guilabel:`Advanced settings`, +and find their respective setting in :ref:`here `. Not all settings in the web interface are per version, but are per project. These settings aren't supported via the configuration file. From 7f520a4f2468728b013e193805142dd16dc7c557 Mon Sep 17 00:00:00 2001 From: Santos Gallegos Date: Wed, 23 Jan 2019 12:22:50 -0500 Subject: [PATCH 44/47] Be more explicit about python.install default --- docs/config-file/v2.rst | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/config-file/v2.rst b/docs/config-file/v2.rst index 0566c19b8d3..6d9419b11d6 100644 --- a/docs/config-file/v2.rst +++ b/docs/config-file/v2.rst @@ -104,6 +104,10 @@ python.install `````````````` List of installation methods of packages and requirements. +You can have several of the following methods. + +:Type: ``list`` +:Default: ``[]`` Requirements file ''''''''''''''''' From 5e0b7718717157494223140ba065f2a51a646dfa Mon Sep 17 00:00:00 2001 From: Santos Gallegos Date: Wed, 23 Jan 2019 12:32:20 -0500 Subject: [PATCH 45/47] More generic description for submodules --- docs/config-file/v2.rst | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/docs/config-file/v2.rst b/docs/config-file/v2.rst index 6d9419b11d6..e95b6e7aef8 100644 --- a/docs/config-file/v2.rst +++ b/docs/config-file/v2.rst @@ -321,7 +321,11 @@ This means that the build stops at the first warning and exits with exit status submodules ~~~~~~~~~~ -Git submodules configuration. +VCS submodules configuration. + +.. note:: + + Only Git is supported at the moment. .. note:: From 329286f2f8c811c6bda37f664546de73945dfe37 Mon Sep 17 00:00:00 2001 From: Santos Gallegos Date: Wed, 23 Jan 2019 12:40:34 -0500 Subject: [PATCH 46/47] Fix broken link --- docs/config-file/v1.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/config-file/v1.rst b/docs/config-file/v1.rst index 232ec5c4b3f..391791c63dc 100644 --- a/docs/config-file/v1.rst +++ b/docs/config-file/v1.rst @@ -8,7 +8,7 @@ Read the Docs now has support for configuring builds with a YAML file. Version 1 shouldn't be used. The version 2 of the configuration file is now avaliable. - See the :ref:`new features ` + See the :ref:`new features ` and :ref:`how to migrate from v1 `. Here is an example of what this file looks like: From f4a5f07d0e940decc1f0e6d3439cfba47ae38622 Mon Sep 17 00:00:00 2001 From: Santos Gallegos Date: Tue, 29 Jan 2019 18:26:45 -0500 Subject: [PATCH 47/47] Update versions --- docs/config-file/v2.rst | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/config-file/v2.rst b/docs/config-file/v2.rst index e95b6e7aef8..9c79ae1e924 100644 --- a/docs/config-file/v2.rst +++ b/docs/config-file/v2.rst @@ -13,7 +13,7 @@ Here is an example of how this file looks like: version: 2 python: - version: 3.6 + version: 3.7 install: - method: pip path: . @@ -82,7 +82,7 @@ Example: .. code-block:: yaml python: - version: 3.6 + version: 3.7 install: - requirements: docs/requirements.txt - method: pip @@ -125,7 +125,7 @@ Example: .. code-block:: yaml python: - version: 3.6 + version: 3.7 install: - requirements: docs/requirements.txt - requirements: requirements.txt @@ -165,7 +165,7 @@ Example: .. code-block:: yaml python: - version: 3.6 + version: 3.7 install: - method: pip path: . @@ -225,7 +225,7 @@ Example: image: latest python: - version: 3.6 + version: 3.7 build.image @@ -240,8 +240,8 @@ The Docker image used for building the docs. Each image support different Python versions and has different packages installed, as defined here: -* `stable `_: :buildpyversions:`2.0` -* `latest `_: :buildpyversions:`3.0` +* `stable `_: :buildpyversions:`3.0` +* `latest `_: :buildpyversions:`4.0` sphinx ~~~~~~