Pin the version in the stable install docs

When building documentation for a tagged release in ReadTheDocs, pin the
version we suggest users to install to a version matching the
documentation they are reading.

For example, a ReadTheDocs build for the v1.9.0 tag would suggest users
to run "pip install cocotb =~ 1.9.0", which gives them a 1.9.x version
matching the documentation they are reading.

For all other Sphinx build types (local builds, PR builds, "latest" RTD
builds, etc.), the documentation stays as is: it gives instructions how
to install the latest stable release (whatever that might be currently),
and also shows how to install a development release.

(cherry picked from commit 61cb17b)

documentation/source/conf.py

@@ -84,6 +84,15 @@
 v_major, v_minor = LooseVersion(release).version[:2]
 version = "{}.{}".format(v_major, v_minor)
 
+# Is this documentation build a ReadTheDocs build for a git tag, i.e., a
+# release? Set the 'is_release_build' tag then, which can be used by the
+# '.. only::' directive.
+# https://docs.readthedocs.io/en/stable/reference/environment-variables.html
+is_rtd_tag = 'READTHEDOCS' in os.environ and os.environ.get('READTHEDOCS_VERSION_TYPE', 'unknown') == 'tag'
+
+if is_rtd_tag:
+    tags.add('is_release_build')
+
 autoclass_content = "both"
 
 autodoc_typehints = "description"  # show type hints in the list of parameters

documentation/source/install.rst

@@ -78,11 +78,22 @@ The installation instructions vary depending on your operating system:
 Installation of cocotb
 ======================
 
-The **stable version** of cocotb can be installed by running
+.. only:: is_release_build
 
-.. code-block:: bash
+    You are reading the documentation for cocotb |version|.
+    To install this version, or any later compatible version, run
 
-    pip install cocotb
+    .. parsed-literal::
+
+        pip install cocotb =~ |version|
+
+.. only:: not is_release_build
+
+    The latest **stable version** of cocotb can be installed by running
+
+    .. code-block:: bash
+
+        pip install cocotb
 
 .. note::