Merge pull request #8390 from readthedocs/env-vars-docs

Docs: environment variables

Author: astrojuanlu

docs/api/v3.rst

@@ -1277,7 +1277,7 @@ Environment Variables are variables that you can define for your project.
 These variables are used in the build process when building your documentation.
 They are for example useful to define secrets in a safe way that can be used by your documentation to build properly.
 Environment variables can also be made public, allowing for them to be used in PR builds.
-See :doc:`/guides/environment-variables`
+See :doc:`/environment-variables`.
 
 
 Environment Variable details

docs/builds.rst

@@ -89,7 +89,7 @@ The *Sphinx* and *Mkdocs* builders set the following RTD-specific environment va
 
    In case extra environment variables are needed to the build process (like secrets, tokens, etc),
    you can add them going to :guilabel:`Admin` > :guilabel:`Environment Variables` in your project.
-   See :doc:`guides/environment-variables`.
+   See :doc:`/environment-variables`.
 
 
 Docker images

docs/environment-variables.rst

@@ -0,0 +1,48 @@
+Environment Variables
+=====================
+
+Read the Docs provides a way to define environment variables for your project to be used in the build process.
+They will be exposed to all the commands executed when building your documentation.
+
+For example, it may happen that your documentation depends on an authenticated service to be built properly.
+In this case, you will require some secrets to access these services.
+
+To define an environment variable, you need to
+
+#. Go to your project's :guilabel:`Admin` > :guilabel:`Environment Variables`
+#. Click on :guilabel:`Add Environment Variable`
+#. Fill the ``Name`` and ``Value`` (your secret)
+#. 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 ``conf.py`` file:
+
+.. code-block:: python
+
+   # 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),
+   )

docs/guides/environment-variables.rst

@@ -128,7 +128,7 @@ Now we can add the link to the private project with the token like:
 
 You can use your tokens with environment variables,
 so you don't have to hard code them in your ``conf.py`` file.
-See :doc:`/guides/environment-variables` to use environment variables inside Read the Docs.
+See :doc:`/environment-variables` to use environment variables inside Read the Docs.
 
 For example,
 if you create an environment variable named ``RTD_TOKEN_DOCS`` with the token from the "docs" project.

docs/guides/intersphinx.rst

@@ -12,7 +12,6 @@ These guides will help you customize or tune aspects of Read the Docs.
    conda
    deprecating-content
    embedding-content
-   environment-variables
    feature-flags
    google-analytics
    hiding-a-version

docs/guides/platform.rst

@@ -34,7 +34,7 @@ To install the package,
 you need to add the URI in your :ref:`requirements file <config-file/v2:Requirements file>`.
 Pip will automatically expand environment variables in your URI,
 so you don't have to hard code the token in the URI.
-See :doc:`using environment variables in Read the Docs </guides/environment-variables>` for more information.
+See :doc:`using environment variables in Read the Docs </environment-variables>` for more information.
 
 .. note::
 
@@ -108,7 +108,7 @@ If you are using a repository manager like *pypiserver*, or *Nexus Repository*,
 you need to set the :option:`pip:--index-url` option.
 You have two ways of set that option:
 
-- Set the ``PIP_INDEX_URL`` :doc:`environment variable in Read the Docs </guides/environment-variables>` with the index URL.
+- Set the ``PIP_INDEX_URL`` :doc:`environment variable in Read the Docs </environment-variables>` with the index URL.
   See :ref:`pip:using environment variables`.
 - Put ``--index-url=https://my-index-url.com/`` at the top of your requirements file.
   See :ref:`pip:requirements file format`.

docs/guides/private-python-packages.rst

@@ -87,7 +87,8 @@ and some of the core features of Read the Docs.
 * **Read the Docs build process**:
   :doc:`Configuration reference </config-file/index>` |
   :doc:`Build process </builds>` |
-  :doc:`/badges` |
+  :doc:`/environment-variables` |
+  :doc:`/badges`
 
 * **Troubleshooting**:
   :doc:`/support` |
@@ -111,6 +112,7 @@ and some of the core features of Read the Docs.
    /connected-accounts
 
    /builds
+   /environment-variables
    /badges
 
    /support