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

@@ -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),

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,
         }

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(