Docs: Refactor "Environment variables" into 3 articles (Diátaxis)

docs/user/build-customization.rst

@@ -70,7 +70,7 @@ In that case, a config file similar to this one can be used:
 There are some caveats to knowing when using user-defined jobs:
 
 * The current working directory is at the root of your project's cloned repository
-* Environment variables are expanded in the commands (see :doc:`environment-variables`)
+* Environment variables are expanded for each individual command (see :doc:`/reference/environment-variables`)
 * Each command is executed in a new shell process, so modifications done to the shell environment do not persist between commands
 * Any command returning non-zero exit code will cause the build to fail immediately
   (note there is a special exit code to `cancel the build <cancel-build-based-on-a-condition>`_)

docs/user/builds.rst

@@ -16,7 +16,7 @@ It also allows you customize the steps of the build process.
 .. note::
 
    All the steps are run inside a Docker container with the image the project defines in :ref:`config-file/v2:build.os`,
-   and all the :doc:`/environment-variables` defined are exposed to them.
+   and all the :doc:`pre-defined environment variables </reference/environment-variables>` and :doc:`custom environment variables </environment-variables>` defined are exposed to them.
 
 
 The following are the pre-defined jobs executed by Read the Docs:

docs/user/environment-variables.rst

@@ -1,109 +1,77 @@
-Environment Variables
-=====================
+.. _Environment Variables:
 
-Read the Docs supports two types of environment variables in project builds:
+Configuring environment variables
+=================================
 
-* `Default environment variables`_
-* `User-defined environment variables`_
+Read the Docs allows you to define your own environment variables to be used in the build process.
+This is useful for adding build secrets such as API tokens.
 
-Both are merged together during the build process and are exposed to all of the executed commands. There are two exceptions for user-defined environment variables however:
+.. The following paragraph is difficult to balance.
+.. We should ideally support environment variables in the Config File,
+.. but as long as it's not supported then people can add environment variables in different ways.
+.. Using the Dashboard is a good approach
+.. but adding an environment variable with ``ENV=123 command --flag`` is possibly better.
 
-* User-defined variables are not available during the checkout step of the :doc:`build process </builds>`
-* User-defined variables that are not marked as public will not be available in :doc:`pull request builds </pull-requests>`
+Environment variables are defined in the :term:`dashboard` interface in :menuselection:`Admin --> Environment variables`.
+In cases where the environment variable isn't a secret,
+there are also :ref:`environment-variables:alternative approaches`.
 
-Default environment variables
------------------------------
+Environment variables are configured and managed for a project's entire build process `with 2 exceptions <Environment variables and build environments>`_.
 
-Read the Docs builders set the following environment variables automatically for each documentation build:
+.. seealso::
 
-.. envvar:: READTHEDOCS
+   :doc:`/guides/environment-variables`
+     A practical example of adding and accessing custom environment variables.
 
-    Whether the build is running inside Read the Docs.
+   :doc:`/reference/environment-variables`
+     Reference to all pre-defined environment variables for your build environments.
 
-    :Default: ``True``
+   :ref:`Public API reference: Environment variables <api/v3:Environment Variables>`
+     Reference for managing custom environments via Read the Docs' API.
 
-.. envvar:: READTHEDOCS_VERSION
+Environment variables and build process
+---------------------------------------
 
-    The :term:`slug` of the version being built, such as ``latest``, ``stable``,
-    or a branch name like ``feature-1234``. For :doc:`pull request builds </pull-requests>`,
-    the value will be the pull request number.
+When a :doc:`build process </builds>` is started,
+:doc:`pre-defined environment variables </reference/environment-variables>` and custom environment variables are added *at each step* of the build process.
+The two sets of environment variables are merged together during the build process and are exposed to all of the executed commands,
+with pre-defined variables taking precedence over custom environment variables.
 
-.. envvar:: READTHEDOCS_VERSION_NAME
+There are two noteworthy exceptions for *custom environment variables*:
 
-    The verbose name of the version being built, such as ``latest``, ``stable``,
-    or a branch name like ``feature/1234``.
+Build checkout step
+  Custom environment variables are **not** available during the checkout step of the :doc:`build process </builds>`
+Pull Request builds
+  Custom environment variables that are not marked as :guilabel:`Public` will not be available in :doc:`pull request builds </pull-requests>`
 
-.. envvar:: READTHEDOCS_VERSION_TYPE
+.. the presence of this section is intended to evolve into a better explanation
+.. with a few more scenarios,
+.. once there is better options for environment variables in config files
 
-    The type of the version being built.
+Alternative approaches
+----------------------
 
-    :Values: ``branch``, ``tag``, ``external`` (for :doc:`pull request builds </pull-requests>`), or ``unknown``
+In some scenarios, it's more feasible to define your build's environment variables using the ``.readthedocs.yaml`` :doc:`configuration file </config-file/index>`.
+Using the :term:`dashboard` for administering environment variables may not be the right fit if you already know that you want to manage environment variables *as code*.
 
-.. envvar:: READTHEDOCS_PROJECT
+Consider the following scenario:
 
-    The :term:`slug` of the project being built. For example, ``my-example-project``.
+* The environment variable **is not** a secret.
 
-.. envvar:: READTHEDOCS_LANGUAGE
+  **and**
+* The environment variable is used just once for a custom command.
 
-    The locale name, or the identifier for the locale, for the project being built.
-    This value comes from the project's configured language.
-
-    :Examples: ``en``, ``it``, ``de_AT``, ``es``, ``pt_BR``
-
-User-defined environment variables
-----------------------------------
-
-If extra environment variables are needed in the build process (like an API token),
-you can define them from the project's settings page:
-
-#. Go to your project's :guilabel:`Admin` > :guilabel:`Environment Variables`
-#. Click on :guilabel:`Add Environment Variable`
-#. Fill the ``Name`` and ``Value``
-#. Check the :guilabel:`Public` option if you want to expose this environment variable
-   to :doc:`builds from pull requests </pull-requests>`.
-
-   .. warning::
-
-      If you mark this option, any user that can create a pull request
-      on your repository will be able to see the value of this environment variable.
-
-#. Click on :guilabel:`Save`
-
-.. note::
-
-   Once you create an environment variable,
-   you won't be able to see its value anymore.
-
-After adding an environment variable,
-you can read it from your build process,
-for example in your Sphinx's configuration file:
-
-.. code-block:: python
-   :caption: conf.py
-
-   import os
-   import requests
-
-   # Access to our custom environment variables
-   username = os.environ.get("USERNAME")
-   password = os.environ.get("PASSWORD")
-
-   # Request a username/password protected URL
-   response = requests.get(
-       "https://httpbin.org/basic-auth/username/password",
-       auth=(username, password),
-   )
-
-You can also use any of these variables from :term:`user-defined build jobs` in your project's configuration file:
+In this case, you can define the environment variable *as code* using :doc:`/build-customization`.
+The following example shows how a non-secret single-purpose environment variable can also be used.
 
 .. code-block:: yaml
    :caption: .readthedocs.yaml
 
    version: 2
    build:
-     os: ubuntu-22.04
+     os: "ubuntu-22.04"
      tools:
-       python: 3.10
+       python: "3.11"
      jobs:
-       post_install:
-         - curl -u ${USERNAME}:${PASSWORD} https://httpbin.org/basic-auth/username/password
+       post_build:
+         - EXAMPLE_ENVIRONMENT_VARIABLE=foobar command --flag

docs/user/guides/administrators.rst

@@ -29,4 +29,5 @@ have a look at our :doc:`/tutorial/index`.
    setup-single-sign-on-github-gitlab-bitbucket
    setup-single-sign-on-google-email
    manage-read-the-docs-teams
+   Use custom environment variables <environment-variables>
    redirects

docs/user/guides/environment-variables.rst

@@ -0,0 +1,87 @@
+How to use custom environment variables
+=======================================
+
+If extra environment variables are needed in the build process,
+you can define them from the project's :term:`dashboard`.
+
+.. seealso::
+
+   :doc:`/environment-variables`
+     Learn more about how Read the Docs applies environment variables in your builds.
+
+Go to your project's :menuselection:`Admin --> Environment Variables` and click on :guilabel:`Add Environment Variable`.
+You will then see the form for adding an environment variable:
+
+.. image:: /img/screenshot_environment_variables.png
+   :alt: Screenshot of the form for adding an environment variable
+
+#. Fill in the :guilabel:`Name` field, this is the name of your variable, for instance ``SECRET_TOKEN`` or ``PIP_EXTRA_INDEX_URL``.
+#. Fill in the :guilabel:`Value` field with the environment variable's value, for instance a secret token or a build configuration.
+#. Check the :guilabel:`Public` option if you want to expose this environment variable
+   to :doc:`builds from pull requests </pull-requests>`.
+
+   .. warning::
+
+      If you mark this option, any user that can create a pull request
+      on your repository will be able to see the value of this environment variable.
+      In other words,
+      do not use this option if your environment variable is a secret.
+
+.. note::
+
+   Once you create an environment variable,
+   you won't be able to edit or view its value in the :term:`dashboard`.
+
+
+Finally, click on :guilabel:`Save`.
+Your custom environment variable is immediately active for all future builds
+and you are ready to start using it.
+
+In the next sections,
+you can see a few examples of using environment variables. ⬇️
+
+Accessing environment variables in code
+---------------------------------------
+
+After adding an environment variable,
+you can read it from your build process,
+for example in your Sphinx's configuration file:
+
+.. code-block:: python
+   :caption: conf.py
+
+   import os
+   import requests
+
+   # Access to our custom environment variables
+   username = os.environ.get("USERNAME")
+   password = os.environ.get("PASSWORD")
+
+   # Request a username/password protected URL
+   response = requests.get(
+       "https://httpbin.org/basic-auth/username/password",
+       auth=(username, password),
+   )
+
+Accessing environment variables in build commands
+-------------------------------------------------
+
+You can also use any of these variables from :term:`user-defined build jobs` in your project's configuration file:
+
+.. code-block:: yaml
+   :caption: .readthedocs.yaml
+
+   version: 2
+   build:
+     os: ubuntu-22.04
+     tools:
+       python: 3.10
+     jobs:
+       post_install:
+         - curl -u ${USERNAME}:${PASSWORD} https://httpbin.org/basic-auth/username/password
+
+.. note::
+
+   If you use ``${SECRET_ENV}`` in a command in ``.readthedocs.yaml``,
+   the private value of the environment variable is not substituted in log entries of the command.
+   It will also be logged as ``${SECRET_ENV}``.

docs/user/index.rst

@@ -80,6 +80,7 @@ to help you create fantastic documentation for your project.
    /build-notifications
    /integrations
    /custom-domains
+   /environment-variables
    /pull-requests
    /connected-accounts
    /downloadable-documentation
@@ -113,6 +114,7 @@ to help you create fantastic documentation for your project.
    /reference/features
    /server-side-search/syntax
    /reference/policies
+   /reference/environment-variables
 
 
 Read the Docs feature overview
@@ -142,6 +144,7 @@ and some of the core features of Read the Docs.
   :doc:`Build process </builds>` |
   :doc:`Build customization </build-customization>` |
   :doc:`/environment-variables` |
+  :doc:`/reference/environment-variables` |
   :doc:`/badges`
 
 * **Troubleshooting**:
@@ -161,7 +164,6 @@ and some of the core features of Read the Docs.
 
    /builds
    /build-customization
-   /environment-variables
 
    /support
 

docs/user/reference/environment-variables.rst

@@ -0,0 +1,38 @@
+Environment variables
+=====================
+
+All :doc:`build processes </builds>` have the following environment variables automatically defined and available for each build step:
+
+.. envvar:: READTHEDOCS
+
+    Whether the build is running inside Read the Docs.
+
+    :Default: ``True``
+
+.. envvar:: READTHEDOCS_VERSION
+
+    The :term:`slug` of the version being built, such as ``latest``, ``stable``,
+    or a branch name like ``feature-1234``. For :doc:`pull request builds </pull-requests>`,
+    the value will be the pull request number.
+
+.. envvar:: READTHEDOCS_VERSION_NAME
+
+    The verbose name of the version being built, such as ``latest``, ``stable``,
+    or a branch name like ``feature/1234``.
+
+.. envvar:: READTHEDOCS_VERSION_TYPE
+
+    The type of the version being built.
+
+    :Values: ``branch``, ``tag``, ``external`` (for :doc:`pull request builds </pull-requests>`), or ``unknown``
+
+.. envvar:: READTHEDOCS_PROJECT
+
+    The :term:`slug` of the project being built. For example, ``my-example-project``.
+
+.. envvar:: READTHEDOCS_LANGUAGE
+
+    The locale name, or the identifier for the locale, for the project being built.
+    This value comes from the project's configured language.
+
+    :Examples: ``en``, ``it``, ``de_AT``, ``es``, ``pt_BR``