From 096e292a59df096059e8f320a0b1789fc60e5bc9 Mon Sep 17 00:00:00 2001 From: Benjamin Bach Date: Fri, 9 Jun 2023 16:01:01 +0200 Subject: [PATCH 1/9] Scissor out and refine changes from #9921 --- docs/user/config-file/index.rst | 120 +++++++++++++++++++++++++---- docs/user/config-file/v2.rst | 34 ++++++-- docs/user/explanation/advanced.rst | 37 +++++++++ docs/user/index.rst | 17 ++-- 4 files changed, 178 insertions(+), 30 deletions(-) create mode 100644 docs/user/explanation/advanced.rst diff --git a/docs/user/config-file/index.rst b/docs/user/config-file/index.rst index a853933444d..8df9c73e742 100644 --- 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 `. + +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 + :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 index 5461ecaa390..e70c9f1853e 100644 --- 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 ` 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 new file mode 100644 index 00000000000..44c49c52e43 --- /dev/null +++ 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 index 604b429796c..d7f41f2d311 100644 --- 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 ` 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` From c7279274402946848850b902eabe6d7c335d4fb3 Mon Sep 17 00:00:00 2001 From: Benjamin Bach Date: Wed, 14 Jun 2023 12:40:15 +0200 Subject: [PATCH 2/9] Polish intro sentences --- docs/user/config-file/index.rst | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/docs/user/config-file/index.rst b/docs/user/config-file/index.rst index 8df9c73e742..6030f5aad62 100644 --- a/docs/user/config-file/index.rst +++ b/docs/user/config-file/index.rst @@ -1,16 +1,15 @@ Using a configuration file ========================== -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**. +During a documentation project's life, both content and structure of the documentation may undergo big and small changes. +And eventually, the configuration of a documentation project also changes. In this article, -we cover the major concepts that are applied in our configuration file: +we cover the major concepts that are applied by having a configuration file: Versioning the configuration - When the documentation project changes, - its configuration often changes alongside. + A documentation project and its configuration file live together in a Git repository + and are versioned together. Configuration as code A commonly used term which is good to know the background and meaning of. From 59d431d684898b6d177b2637a76f14210544a249 Mon Sep 17 00:00:00 2001 From: Benjamin Bach Date: Wed, 14 Jun 2023 12:45:50 +0200 Subject: [PATCH 3/9] Add how-to reference --- docs/user/config-file/index.rst | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/user/config-file/index.rst b/docs/user/config-file/index.rst index 6030f5aad62..cd015703725 100644 --- a/docs/user/config-file/index.rst +++ b/docs/user/config-file/index.rst @@ -17,13 +17,15 @@ Configuration as code 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:`/guides/setup/configuration-file` + Here are the practical steps to add a configuration file to your documentation project. + :doc:`/config-file/v2` Reference of all the settings offered in the build configuration file. + Why version your project's configuration? ----------------------------------------- From 63680bc63e481dec1c28ccaaf6956afbd509cb78 Mon Sep 17 00:00:00 2001 From: Eric Holscher <25510+ericholscher@users.noreply.github.com> Date: Wed, 14 Jun 2023 13:37:47 -0700 Subject: [PATCH 4/9] Do some content updates. --- docs/user/config-file/index.rst | 62 +++++++++++++++--------------- docs/user/config-file/v2.rst | 20 +++++----- docs/user/explanation/advanced.rst | 13 ++----- 3 files changed, 44 insertions(+), 51 deletions(-) diff --git a/docs/user/config-file/index.rst b/docs/user/config-file/index.rst index cd015703725..6f4c07888b5 100644 --- a/docs/user/config-file/index.rst +++ b/docs/user/config-file/index.rst @@ -1,29 +1,33 @@ Using a configuration file ========================== -During a documentation project's life, both content and structure of the documentation may undergo big and small changes. +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. In this article, -we cover the major concepts that are applied by having a configuration file: +we cover the major concepts of using a configuration file: Versioning the configuration A documentation project and its configuration file live together in a Git repository and are versioned together. Configuration as code - A commonly used term which is good to know the background and meaning of. + 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 *configuration as code*. +Options that are not found in the configuration file + Not everything is suitable for version-specific configuration, + like the Git repository where the config file is read after cloning. .. seealso:: :doc:`/guides/setup/configuration-file` - Here are the practical steps to add a configuration file to your documentation project. + Practical steps to add a configuration file to your documentation project. :doc:`/config-file/v2` - Reference of all the settings offered in the build configuration file. + Reference for configuration file settings. Why version your project's configuration? @@ -33,27 +37,25 @@ 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. + What is installed, how it's installed and what installs can change, + especially across multiple verisons. - For instance, - you might change between Pip, Pipenv, Conda etc. + 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 tool setups change ⚙ī¸ +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. -Switching documentation tools đŸ’Ŗī¸ - Long-lived software projects can go through many phases in their history. - This includes changing the documentation tool. +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 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. +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: @@ -69,25 +71,24 @@ The main advantages of using a configuration file over the web interface are: 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. +"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 in general have a ``requirements.txt`` or similar. +* 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. - -Expressing a configuration *as code* is therefore considered by many to be the easier option. +*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 by copy-pasting a template and adapting it. +you can usually start with 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, @@ -106,12 +107,11 @@ 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 +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 verison. -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`. +The goal over time is to have everything that can be managed in a version-specific YAML file configured that way. .. seealso:: diff --git a/docs/user/config-file/v2.rst b/docs/user/config-file/v2.rst index a654f2ac77b..0071b6f593e 100644 --- a/docs/user/config-file/v2.rst +++ b/docs/user/config-file/v2.rst @@ -1,14 +1,14 @@ -Configuration file .readthedocs.yaml -==================================== +Configuration file v2 (.readthedocs.yaml) +========================================= -Read the Docs supports configuring your documentation builds with a YAML file. -It's required to be named ``.readthedocs.yaml`` and be placed in the root of your Git repository. +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 file can contain a number of settings that are not accessible through the Read the Docs website. +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. +**This allows you to store different configurations for different versions of your documentation.** Below is an example YAML file which shows the most common configuration options: @@ -907,11 +907,11 @@ These settings aren't supported via the configuration file. * ``Privacy level`` * ``Analytics code`` -Custom sub-folder for .readthedocs.yaml ---------------------------------------- +Custom paths for .readthedocs.yaml +---------------------------------- In order to support *monorepo* layouts, -it's possible to configure the sub-folder where your ``.readthedocs.yaml`` is found. +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. @@ -925,4 +925,4 @@ Previous version: v1 -------------------- Version 1 is deprecated and using it is discouraged, -view its reference here :doc:`/config-file/v2`. +view its reference here :doc:`/config-file/v1`. diff --git a/docs/user/explanation/advanced.rst b/docs/user/explanation/advanced.rst index 44c49c52e43..323c7b06f2e 100644 --- a/docs/user/explanation/advanced.rst +++ b/docs/user/explanation/advanced.rst @@ -5,26 +5,19 @@ 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. + An explanation of the value of having a versioned configuration file for your project. ⏊ī¸ :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. + *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 that can be read offline to your documentation and keep them versioned. + 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. - This is a general introduction to environment variables on our platform, both pre-defined and custom environment variables. - .. toctree:: :maxdepth: 2 From d0ec911b123a475c027197a2d50f9fa7ff9b7055 Mon Sep 17 00:00:00 2001 From: Benjamin Bach Date: Thu, 15 Jun 2023 12:51:16 +0200 Subject: [PATCH 5/9] =?UTF-8?q?Emoji=20=E2=9A=96=EF=B8=8F?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/user/config-file/index.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/user/config-file/index.rst b/docs/user/config-file/index.rst index 6f4c07888b5..14735604fe3 100644 --- a/docs/user/config-file/index.rst +++ b/docs/user/config-file/index.rst @@ -49,7 +49,7 @@ Documentation tools change ⚙ī¸ 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 +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. From 5a0dc883fd97cd1231e606384e4d8354a6f8ef67 Mon Sep 17 00:00:00 2001 From: Benjamin Bach Date: Thu, 15 Jun 2023 12:55:46 +0200 Subject: [PATCH 6/9] fix mini err --- docs/user/config-file/index.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/user/config-file/index.rst b/docs/user/config-file/index.rst index 14735604fe3..8a67433f4e9 100644 --- a/docs/user/config-file/index.rst +++ b/docs/user/config-file/index.rst @@ -88,7 +88,7 @@ Such configurations are hard to copy between projects and also hard to introspec *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 adapting it. +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, From 5feb0ffaaf49cb5b566635cfb2ebd55047181d1b Mon Sep 17 00:00:00 2001 From: Benjamin Bach Date: Thu, 15 Jun 2023 12:56:31 +0200 Subject: [PATCH 7/9] typo fix --- docs/user/config-file/index.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/user/config-file/index.rst b/docs/user/config-file/index.rst index 8a67433f4e9..ee9cbd71963 100644 --- a/docs/user/config-file/index.rst +++ b/docs/user/config-file/index.rst @@ -109,7 +109,7 @@ Git settings 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 verison. + they are configured for the project itself, and not a specific version. The goal over time is to have everything that can be managed in a version-specific YAML file configured that way. From 9c3d1127859c3335e95f8e5d5af9ec9bfe1a4e7d Mon Sep 17 00:00:00 2001 From: Benjamin Bach Date: Thu, 15 Jun 2023 13:08:07 +0200 Subject: [PATCH 8/9] typo fixes --- docs/user/config-file/index.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/user/config-file/index.rst b/docs/user/config-file/index.rst index ee9cbd71963..f36701d283e 100644 --- a/docs/user/config-file/index.rst +++ b/docs/user/config-file/index.rst @@ -19,7 +19,7 @@ Configuration as code Options that are not found in the configuration file Not everything is suitable for version-specific configuration, - like the Git repository where the config file is read after cloning. + like the Git repository where the configuration file is read after cloning. .. seealso:: @@ -38,7 +38,7 @@ 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 verisons. + 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. From ef720d9df371ea0cfdf154cb065e61d5e90614ae Mon Sep 17 00:00:00 2001 From: Benjamin Bach Date: Thu, 15 Jun 2023 13:08:25 +0200 Subject: [PATCH 9/9] 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 --- docs/user/config-file/v2.rst | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs/user/config-file/v2.rst b/docs/user/config-file/v2.rst index 0071b6f593e..a5fc697166f 100644 --- a/docs/user/config-file/v2.rst +++ b/docs/user/config-file/v2.rst @@ -29,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 ------------------