Config file v2 docs

docs/.rstcheck.cfg

@@ -1,4 +1,4 @@
 [rstcheck]
 ignore_directives=automodule,http:get,tabs,tab,prompt
-ignore_roles=djangosetting,setting
+ignore_roles=djangosetting,setting,buildpyversions
 ignore_messages=(Duplicate implicit target name: ".*")|(Hyperlink target ".*" is not referenced)

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 <yaml-config>`.
+but you can change that using a :doc:`config-file/index`.
 
 .. note::
 

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`, 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:
@@ -42,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/
-

docs/config-file/index.rst

@@ -0,0 +1,28 @@
+Configuration File
+==================
+
+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:
+
+- ``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
+- The settings are per version rather than per project.
+- The settings live in your VCS.
+- Reproducible build environments over time.
+
+.. tip::
+
+   Using a configuration file is the recommended way of using Read the Docs.
+
+.. toctree::
+    :maxdepth: 3
+
+    Version 2 <v2>
+    Version 1 <v1>

docs/yaml-config.rst → docs/config-file/v1.rst

@@ -1,12 +1,15 @@
-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.
+:doc:`The Read the Docs file <index>` 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.
+.. warning::
 
+   Version 1 shouldn't be used.
+   The version 2 of the configuration file is now avaliable.
+   See the :ref:`new features <config-file/v2:New>`
+   and :ref:`how to migrate from v1 <config-file/v2:Migrating from v1>`.
 
 Here is an example of what this file looks like:
 
@@ -25,6 +28,15 @@ Here is an example of what this file looks like:
 Supported settings
 ------------------
 
+version
+~~~~~~~
+
+* Default: 1
+
+.. code-block:: yaml
+
+   version: 1
+
 .. _yaml__formats:
 
 formats
@@ -161,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.