diff --git a/docs/user/config-file/index.rst b/docs/user/config-file/index.rst index a853933444d..9bf7ea8ddad 100644 --- a/docs/user/config-file/index.rst +++ b/docs/user/config-file/index.rst @@ -1,27 +1,66 @@ -Configuration file -================== +.. TODO: Use new glossary terms added in another PR -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``. +Versioning your configuration +============================= -.. note:: +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**. - Some other variants like ``readthedocs.yaml``, ``.readthedocs.yml``, etc - are deprecated. +But changing your configuration for your documentation's version 2.x should not make it impossible to keep maintaining the documentation for version 1.x using a previous configuration. + +.. seealso:: + + :doc:`/config-file/v2` + Reference of all the settings offered in the build configuration file. + +Consider the following aspects of a documentation project: + +:Build environment: + 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 tools: + Using Sphinx? Using MkDocs? Or some other tool? + All these tools have their own configuration files and special ways to invoke them. + + Changing the documentation tool should also be possible in the lifecycle of your documentation. + Read the Docs understands outputs from several different documentation tools and therefore, + it's possible to change documentation tools between different versions of documentation. + + +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. + +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. - Using a configuration file is the recommended way of using Read the Docs. +Because of its fragility and uniqueness, +the alternative to "Configuration as Code" is also often referred to as snowflake ❄️ configuration. -.. 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 01d83afe0c7..7c7f9ecdaa7 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:: @@ -942,3 +946,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 index 02eddc50e22..38b520c105f 100644 --- a/docs/user/explanation/advanced.rst +++ b/docs/user/explanation/advanced.rst @@ -4,6 +4,11 @@ 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` + Configure your documentation build in a configuration file stored in Git: + 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**. + ⏩️ :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. @@ -23,6 +28,7 @@ we explain some of the more specific or advanced concepts of writing documentati :maxdepth: 2 :hidden: + /config-file/index /subprojects /localization /downloadable-documentation diff --git a/docs/user/index.rst b/docs/user/index.rst index b003557c446..3c5babf763f 100644 --- a/docs/user/index.rst +++ b/docs/user/index.rst @@ -41,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 @@ -160,7 +160,7 @@ Need to know how something works? Our references provide the details: 📚 :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` diff --git a/docs/user/versions.rst b/docs/user/versions.rst index 46cb1984b5c..d5e3a8f19c8 100644 --- a/docs/user/versions.rst +++ b/docs/user/versions.rst @@ -12,7 +12,7 @@ we also create a ``stable`` version, tracking your most recent release. If you want a custom ``stable`` version, create either a tag or branch in your project with that name. -When you have :term:`webhook ` configured for your repository, +When you have :term:`webhook` configured for your repository, we will automatically build each version when you push a commit. How we envision versions working