From a185bac9024bb187a14b7bb0534a3a3e8acbfa57 Mon Sep 17 00:00:00 2001
From: Anderson Bravalheri <andersonbravalheri@gmail.com>
Date: Tue, 8 Jun 2021 02:25:03 +0100
Subject: [PATCH] Add READTHEDOCS_VERSION_{TYPE,NAME} env vars

These variables make it easy for configuration scripts to differentiate
between regular builds and builds triggered by PRs.

Moreover, they are quite handy to setting up `html_title` in a way that
matches the version being displayed in the RTD's version switch menu.
---
 docs/builds.rst                            | 14 +++++++++++++-
 readthedocs/projects/tasks.py              |  2 ++
 readthedocs/rtd_tests/tests/test_builds.py |  4 +++-
 3 files changed, 18 insertions(+), 2 deletions(-)

diff --git a/docs/builds.rst b/docs/builds.rst
index 1ba9f0542ba..80916c3b6c0 100644
--- a/docs/builds.rst
+++ b/docs/builds.rst
@@ -80,11 +80,23 @@ The *Sphinx* and *Mkdocs* builders set the following RTD-specific environment va
    :widths: 15, 10, 30
 
    ``READTHEDOCS``, Whether the build is running inside RTD, ``True``
-   ``READTHEDOCS_VERSION``, The RTD name of the version which is being built, ``latest``
+   ``READTHEDOCS_VERSION``, The RTD slug of the version which is being built, ``latest``
+   ``READTHEDOCS_VERSION_NAME``, Corresponding version name as displayed in RTD's version switch menu, ``stable``
+   ``READTHEDOCS_VERSION_TYPE``, Type of the event triggering the build, ``branch`` ``tag`` ``external`` ``unknown``
    ``READTHEDOCS_PROJECT``, The RTD slug of the project which is being built, ``my-example-project``
    ``READTHEDOCS_LANGUAGE``, The RTD language slug of the project which is being built, ``en``
 
 
+.. note::
+
+   - The term "slug" is used here to indicate a string without some types characters
+     considered special in certain circunstances. The version slug can contain some
+     characters not usually present in other slugs.
+
+   - The ``external`` value for ``READTHEDOCS_VERSION_TYPE`` will usually be
+     associated with builds triggered by pull requests. See :doc:`/pull-requests`.
+
+
 .. tip::
 
    In case extra environment variables are needed to the build process (like secrets, tokens, etc),
diff --git a/readthedocs/projects/tasks.py b/readthedocs/projects/tasks.py
index bd4fc03559c..9f4bf8bb3dc 100644
--- a/readthedocs/projects/tasks.py
+++ b/readthedocs/projects/tasks.py
@@ -317,6 +317,8 @@ def get_rtd_env_vars(self):
         env = {
             'READTHEDOCS': 'True',
             'READTHEDOCS_VERSION': self.version.slug,
+            'READTHEDOCS_VERSION_TYPE': self.version.type,
+            'READTHEDOCS_VERSION_NAME': self.version.explicit_name,
             'READTHEDOCS_PROJECT': self.project.slug,
             'READTHEDOCS_LANGUAGE': self.project.language,
         }
diff --git a/readthedocs/rtd_tests/tests/test_builds.py b/readthedocs/rtd_tests/tests/test_builds.py
index a28bb10f33d..db22e5c3aed 100644
--- a/readthedocs/rtd_tests/tests/test_builds.py
+++ b/readthedocs/rtd_tests/tests/test_builds.py
@@ -341,7 +341,7 @@ def test_get_env_vars(self):
             project=project,
         )
         build = get(Build)
-        version = get(Version, slug='1.8', project=project)
+        version = get(Version, slug='1.8', project=project, type=BRANCH)
         task = UpdateDocsTaskStep(
             project=project, version=version, build={'id': build.pk},
         )
@@ -353,6 +353,8 @@ def test_get_env_vars(self):
             'NO_COLOR': '1',
             'READTHEDOCS': 'True',
             'READTHEDOCS_VERSION': version.slug,
+            'READTHEDOCS_VERSION_TYPE': BRANCH,
+            'READTHEDOCS_VERSION_NAME': version.verbose_name,
             'READTHEDOCS_PROJECT': project.slug,
             'READTHEDOCS_LANGUAGE': project.language,
             'BIN_PATH': os.path.join(