diff --git a/docs/user/config-file/index.rst b/docs/user/config-file/index.rst index a853933444d..f36701d283e 100644 --- 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 `. + +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 + :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 77d6ae0d5f4..a5fc697166f 100644 --- 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 ` 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 new file mode 100644 index 00000000000..323c7b06f2e --- /dev/null +++ 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 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`