Docs: Configuration file pages as explanation and reference (Diátaxis) (#10416)

benjaoming · ericholscher · web-flow · commit a0651c5cc6c6 · 2023-06-15T13:19:40.000+02:00
* Scissor out and refine changes from #9921 * Polish intro sentences * Add how-to reference * Do some content updates. * Emoji ⚖️ * fix mini err * typo fix * typo fixes * Adds a seealso to v2 reference -- many people are visiting the reference directly (because we didn't have any other resources), should add the how-to --------- Co-authored-by: Eric Holscher <25510+ericholscher@users.noreply.github.com>
diff --git a/docs/user/config-file/index.rst b/docs/user/config-file/index.rst
@@ -1,27 +1,120 @@
-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``.
+Content and structure of documentation undergo big and small changes.
+And eventually, the configuration of a documentation project also changes.
+This means you need to be able to track these changes over time,
+and keep them up to date.
 
-.. note::
+In this article,
+we cover the major concepts of using a configuration file:
 
-   Some other variants like ``readthedocs.yaml``, ``.readthedocs.yml``, etc
-   are deprecated.
+Versioning the configuration
+  A documentation project and its configuration file live together in a Git repository
+  and are versioned together.
+
+Configuration as code
+  Configuration uses the same workflow as your source code,
+  including being reviewed and tested in a Pull Request.
+
+Options that are not found in the configuration file
+  Not everything is suitable for version-specific configuration,
+  like the Git repository where the configuration file is read after cloning.
+
+.. seealso::
+
+   :doc:`/guides/setup/configuration-file`
+      Practical steps to add a configuration file to your documentation project.
+
+   :doc:`/config-file/v2`
+      Reference for configuration file settings.
+
+
+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 can change,
+  especially across multiple versions.
+
+  You might change between Pip and Poetry.
+  You might also jump between Python 2 and 3 or Python 3.8 and Python 3.10.
+
+Documentation tools 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.
+
+Comparing changes over time ⚖️
+  As your project changes, you will need to change your configuration.
+  You might wonder how something was done in the past,
+  and having it versioned means you can see each commit as it has changed.
+
+You can configure your Read the Docs project by adding a ``.readthedocs.yaml`` file [1]_ to your Git repository.
+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 where the configuration or settings of software is maintained in a Git repository as *code*.
+Contrast this with the approach where configuration is managed inside the software's own UI,
+making it hard to track changes, and copy settings 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 often have a ``requirements.txt`` or ``environment.yaml``.
+
+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.
+
+*Configuration as code* is 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 with a template and adapt 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.
+
+Domain-level settings
+  Since many settings apply to the domain a project is hosted on,
+  they are configured for the project itself, and not a specific version.
 
-   Using a configuration file is the recommended way of using Read the Docs.
+The goal over time is to have everything that can be managed in a version-specific YAML file configured that way.
 
-.. 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 v2 (.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``.
+Read the Docs supports configuring your documentation builds with a configuration file.
+This file is named ``.readthedocs.yaml`` and should be placed in the top level of your Git repository.
+
+The ``.readthedocs.yaml``  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::
@@ -25,6 +29,12 @@ Below is an example YAML file which shows the most common configuration options:
            :caption: .readthedocs.yaml
 
 
+.. seealso::
+
+   :doc:`/guides/setup/configuration-file`
+      Practical steps to add a configuration file to your documentation project.
+
+
 Supported settings
 ------------------
 
@@ -902,3 +912,23 @@ These settings aren't supported via the configuration file.
 * ``Show versions warning``
 * ``Privacy level``
 * ``Analytics code``
+
+Custom paths for .readthedocs.yaml
+----------------------------------
+
+In order to support *monorepo* layouts,
+it's possible to configure the path to 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/v1`.
diff --git a/docs/user/explanation/advanced.rst b/docs/user/explanation/advanced.rst
@@ -0,0 +1,30 @@
+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`
+    An explanation of the value of having a versioned configuration file for your project.
+
+⏩️ :doc:`/subprojects`
+    *Subprojects* are a flexible for gathering multiple projects under the same domain.
+
+⏩️ :doc:`/localization`
+    Learn more about multilingual documentation projects and how translation workflows are supported.
+
+⏩️ :doc:`/downloadable-documentation`
+    An introduction to adding downloadable files, like PDFs, that can be read offline.
+
+⏩️ :doc:`/environment-variables`
+    Environment variables can be used to make your documentation builds flexible and easy to customize.
+
+.. 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`
