Scissor out and refine changes from #9921

benjaoming · benjaoming · commit 096e292a59df · 2023-06-09T16:01:36.000+02:00
diff --git a/docs/user/config-file/index.rst b/docs/user/config-file/index.rst
@@ -1,27 +1,119 @@
-Configuration file
-==================
+Using a 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 should be named ``.readthedocs.yaml``.
+The lifecycle of a documentation project changes both the content and the structure of the documentation.
+In addition to this,
+**the whole configuration of a project also changes**.
 
-.. note::
+In this article,
+we cover the major concepts that are applied in our configuration file:
 
-   Some other variants like ``readthedocs.yaml``, ``.readthedocs.yml``, etc
-   are deprecated.
+Versioning the configuration
+  When the documentation project changes,
+  its configuration often changes alongside.
+
+Configuration as code
+  A commonly used term which is good to know the background and meaning of.
+
+Options that are **not** found in the configuration file
+  Not everything is suitable for *configuration as code*.
+
+.. TODO: Add upcoming configuration file how-to
+
+.. seealso::
+
+   :doc:`/config-file/v2`
+      Reference of all the settings offered in the build configuration file.
+
+Why version your project's configuration?
+-----------------------------------------
+
+Consider the following aspects of a documentation project:
+
+Build environments change 📦️
+  You may depend on a number of packages but your method for installing them changes.
+  What is installed, how it's installed and what installs it can change.
+
+  For instance,
+  you might change between Pip, Pipenv, Conda etc.
+  You might also jump between Python 2 and 3 or Python 3.8 and Python 3.10.
+
+Documentation tool setups change ⚙️
+  Using Sphinx? Using MkDocs? Or some other tool?
+  All these tools have their own configuration files and special ways to invoke them.
+  In order to switch between how you are invoking the tool and setting up its environment,
+  you will need external build configuration.
+
+Switching documentation tools 💣️
+  Long-lived software projects can go through many phases in their history.
+  This includes changing the documentation tool.
+
+
+You can configure your Read the Docs project by adding a special file ``.readthedocs.yaml`` [1]_ to your Git repository.
+
+Because the file is stored in Git,
+the configuration will apply to the exact version that is being built.
+This allows you to store different configurations for different versions of your documentation.
 
 The main advantages of using a configuration file over the web interface are:
 
 - Settings are per version rather than per project.
-- Settings live in your VCS.
+- Settings live in your Git repository.
 - They enable reproducible build environments over time.
 - Some settings are only available using a configuration file
 
-.. tip::
+.. [1] Other variants of the configuration file name like ``readthedocs.yaml``, ``.readthedocs.yml``, etc. are deprecated.
+       You may however, :doc:`configure a custom sub-folder </guides/setup/monorepo>`.
+
+Configuration as Code
+---------------------
+
+"Configuration as Code" is a concept whereby the configuration or settings of software is maintained in a Git repository as *code*.
+Alternatively, configurations are often added and managed inside the software's own UI,
+making it hard to track changes, and reproduce and copy behavior to other projects.
+
+Most users of Read the Docs will already be familiar with the concept since many popular tools already require you to store their configuration in your Git repository:
+
+* Sphinx uses a ``conf.py`` file.
+* MkDocs uses a ``mkdocs.yaml`` file.
+* Python projects in general have a ``requirements.txt`` or similar.
+
+Because of its fragility and uniqueness,
+the alternative to "Configuration as Code" is also often referred to as snowflake ❄️ configuration.
+Such configurations are hard to copy between projects and also hard to introspect for people without authorization to access the configuration UI.
+
+
+Expressing a configuration *as code* is therefore considered by many to be the easier option.
+It might seem harder to have to write the configuration code from scratch,
+but in order to use Read the Docs,
+you can usually start by copy-pasting a template and adapting it.
+
+Read the Docs has chosen to offer as much configuration as possible through the usage of ``.readthedocs.yaml``.
+Our experience is that projects benefit from such a setup,
+and even when the benefits aren't obvious in the beginning of a project's lifecycle,
+they will emerge over time.
+
+What's not covered by ``.readthedocs.yaml``?
+--------------------------------------------
+
+There are a number of things that aren't possible to cover in the configuration file,
+which still belong in your project's Dashboard.
+
+These configuration items are for instance:
+
+Git settings
+  Since the configuration file is stored in Git,
+  it doesn't make sense that it would configure the Git setup.
+
+Custom domains and redirects
+  Settings
 
-   Using a configuration file is the recommended way of using Read the Docs.
+Other general non-versioned settings
+  In general,
+  settings that aren't versioned and do not relate to how your project is built are accessed via your :term:`dashboard`.
 
-.. toctree::
-    :maxdepth: 3
+.. seealso::
 
-    Version 2 <v2>
+   :doc:`/guides/reproducible-builds`
+      In addition to storing your configuration in Git,
+      we also recommend special practices for making your builds resilient to changes in your software dependencies.
diff --git a/docs/user/config-file/v2.rst b/docs/user/config-file/v2.rst
@@ -1,11 +1,15 @@
-Configuration file v2
-=====================
+Configuration file .readthedocs.yaml
+====================================
 
 Read the Docs supports configuring your documentation builds with a YAML file.
-The :doc:`configuration file <index>` must be in the root directory of your project
-and be named ``.readthedocs.yaml``.
+It's required to be named ``.readthedocs.yaml`` and be placed in the root of your Git repository.
+
+The file can contain a number of settings that are not accessible through the Read the Docs website.
+
+Because the file is stored in Git,
+the configuration will apply to the exact version that is being built.
+This allows you to store different configurations for different versions of your documentation.
 
-All options are applied to the version containing this file.
 Below is an example YAML file which shows the most common configuration options:
 
 .. tabs::
@@ -946,3 +950,23 @@ These settings aren't supported via the configuration file.
 * ``Show versions warning``
 * ``Privacy level``
 * ``Analytics code``
+
+Custom sub-folder for .readthedocs.yaml
+---------------------------------------
+
+In order to support *monorepo* layouts,
+it's possible to configure the sub-folder where your ``.readthedocs.yaml`` is found.
+
+Using this configuration makes it possible to create several Read the Docs projects pointing at the same Git repository.
+This is recommended for monorepo layouts that host several documentation projects in the same repository.
+
+.. seealso::
+
+   :doc:`/guides/setup/monorepo`
+      This guide explains how to use the configuration.
+
+Previous version: v1
+--------------------
+
+Version 1 is deprecated and using it is discouraged,
+view its reference here :doc:`/config-file/v2`.
diff --git a/docs/user/explanation/advanced.rst b/docs/user/explanation/advanced.rst
@@ -0,0 +1,37 @@
+Deep dive into Read the Docs
+============================
+
+In this section,
+we explain some of the more specific or advanced concepts of writing documentation on Read the Docs.
+
+⏩️ :doc:`/config-file/index`
+    The lifecycle of a documentation project changes the content and the structure of the documentation.
+    In addition to this,
+    the whole configuration of a project also changes.
+    In this article,
+    we explain some of the fundamental purposes of having a configuration file.
+
+⏩️ :doc:`/subprojects`
+    Thinking about gathering several documentation projects under the same umbrella?
+    This is a common need, and using *subprojects* is a flexible option that is recommended for most cases.
+
+⏩️ :doc:`/localization`
+    Learn more about multilingual documentation projects and how translation workflows are supported.
+
+⏩️ :doc:`/downloadable-documentation`
+    An introduction to adding downloadable files that can be read offline to your documentation and keep them versioned.
+
+⏩️ :doc:`/environment-variables`
+    Environment variables can be used to make your documentation builds flexible and easy to customize.
+    This is a general introduction to environment variables on our platform, both pre-defined and custom environment variables.
+
+
+.. toctree::
+   :maxdepth: 2
+   :hidden:
+
+   /config-file/index
+   /subprojects
+   /localization
+   /downloadable-documentation
+   /environment-variables
diff --git a/docs/user/index.rst b/docs/user/index.rst
@@ -19,10 +19,7 @@ Read the Docs: documentation simplified
 
    /choosing-a-site
    /integrations
-   /downloadable-documentation
-   /environment-variables
-   /subprojects
-   /localization
+   /explanation/advanced
 
 .. toctree::
    :maxdepth: 2
@@ -44,7 +41,7 @@ Read the Docs: documentation simplified
    :caption: 📚 Reference
 
    /reference/features
-   /config-file/index
+   /config-file/v2
    /builds
    /build-customization
    /server-side-search/syntax
@@ -129,14 +126,12 @@ Get a high-level overview of our platform:
 💡 :doc:`/choosing-a-site`
   Learn about the differences between |org_brand| and |com_brand|.
 
+💡 :doc:`/explanation/advanced`
+  Get familiar with some of the more advanced topics of building and deploying documentation with Read the Docs.
+
 💡 :doc:`All explanation articles </explanation/index>`
   Browser all our explanation articles.
 
-.. TODO: This next item needs its article to be finished in a separate PR
-.. https://github.com/readthedocs/readthedocs.org/pull/10071
-.. TODO: 💡 Advanced topics: Deep-dive into Read the Docs
-..  Get familiar with some of the more advanced topics of building and deploying documentation with Read the Docs.
-
 
 How-to guides
 -------------
@@ -171,7 +166,7 @@ Here are a few of the most important reference docs:
 📚 :doc:`/reference/features`
   Overview of all the main features of Read the Docs.
 
-📚 :doc:`/config-file/index`
+📚 :doc:`/config-file/v2`
   Information for our configuration file: ``.readthedocs.yaml``.
 
 📚 :doc:`/builds`
