diff --git a/docs/api/v3.rst b/docs/api/v3.rst index a7b28885c2f..8d873eaf09e 100644 --- a/docs/api/v3.rst +++ b/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 diff --git a/docs/builds.rst b/docs/builds.rst index 1ba9f0542ba..f95bf5031cd 100644 --- a/docs/builds.rst +++ b/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 diff --git a/docs/environment-variables.rst b/docs/environment-variables.rst new file mode 100644 index 00000000000..becb0e922a2 --- /dev/null +++ b/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 `. + + .. 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), + ) diff --git a/docs/guides/environment-variables.rst b/docs/guides/environment-variables.rst deleted file mode 100644 index 588b29b0d89..00000000000 --- a/docs/guides/environment-variables.rst +++ /dev/null @@ -1,39 +0,0 @@ -I Need Secrets (or Environment Variables) in my Build -===================================================== - -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. - -Read the Docs provides a way to define environment variables for your project to be used in the build process. -All these variables will be exposed to all the commands executed when building your documentation. - -To define an environment variable, you need to - -#. Go to your project :guilabel:`Admin` > :guilabel:`Environment Variables` -#. Click on "Add Environment Variable" button -#. Input a ``Name`` and ``Value`` (your secret needed here) -#. Click "Save" button - -.. note:: - - Values will never be exposed to users, even to owners of the project. - Once you create an environment variable, you won't be able to see its value anymore for security purposes. - -After adding an environment variable from your project's admin, you can access it from your build process using Python, -for example: - -.. 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), - ) diff --git a/docs/guides/intersphinx.rst b/docs/guides/intersphinx.rst index 31d938a6d0f..b56936aa9be 100644 --- a/docs/guides/intersphinx.rst +++ b/docs/guides/intersphinx.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. diff --git a/docs/guides/platform.rst b/docs/guides/platform.rst index 737a79c157a..1f4a0171327 100644 --- a/docs/guides/platform.rst +++ b/docs/guides/platform.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 diff --git a/docs/guides/private-python-packages.rst b/docs/guides/private-python-packages.rst index 99706e697e6..9802a9b9c9b 100644 --- a/docs/guides/private-python-packages.rst +++ b/docs/guides/private-python-packages.rst @@ -34,7 +34,7 @@ To install the package, you need to add the URI in your :ref:`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 ` for more information. +See :doc:`using environment variables in Read the Docs ` 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 ` with the index URL. +- Set the ``PIP_INDEX_URL`` :doc:`environment variable in Read the Docs ` 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`. diff --git a/docs/index.rst b/docs/index.rst index 9d94be0f195..1d4c8552839 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -87,7 +87,8 @@ and some of the core features of Read the Docs. * **Read the Docs build process**: :doc:`Configuration reference ` | :doc:`Build process ` | - :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