Better handle setuptools_scm versioning

.readthedocs.yml

@@ -11,6 +11,12 @@ build:
       # to allow setuptools-scm to correctly auto-discover the version.
       - git fetch --unshallow
       - git fetch --all
+    # Need to stash the local changes that Read the Docs makes so that
+    #  setuptools_scm can generate the correct Iris version.
+    pre_install:
+      - git stash
+    post_install:
+      - git stash pop
 
 conda:
   environment: requirements/ci/readthedocs.yml

docs/src/_templates/custom_sidebar_logo_version.html

@@ -1,20 +1,26 @@
 {% if on_rtd %}
     {% if rtd_version == 'latest' %}
         <span title="latest development version">
-            <img src="https://img.shields.io/badge/latest_version-{{ version }}-orange?style=flat">
+            <img src="https://img.shields.io/badge/⚠️_version_('latest')-{{ version }}-gold?style=flat">
         </span>
     {% elif rtd_version == 'stable' %}
         <span title="stable version">
-            <img src="https://img.shields.io/badge/stable_version-{{ version }}-green?style=flat">
+            <img src="https://img.shields.io/badge/✨️_version_('stable')-{{ version }}-green?style=flat">
+        </span>
+    {% elif rtd_version_type == 'tag' %}
+        {# Covers builds for specific tags, including RC's. #}
+        <span title="archived version (not 'stable' or 'latest')">
+            <img src="https://img.shields.io/badge/🔒_version_(archived)-{{ version }}-red?style=?style=flat">
         </span>
     {% else %}
-        <span title="old version (not stable or latest)">
-            <img src="https://img.shields.io/badge/old_version-{{ version }}-red?style=?style=flat">
+        {# Anything else build by RTD will be the HEAD of an activated branch #}
+        <span title="non-tagged branch commit">
+            <img src="https://img.shields.io/badge/🚧_branch-{{ rtd_version }}_@_{{ commit_sha }}-blue?style=?style=flat">
         </span>
     {% endif %}
 {%- else %}
     {# not on rtd #}
-    <span title="development version">
-        <img src="https://img.shields.io/badge/dev_version-{{ version }}-blue?style=?style=flat">
+    <span title="non-tagged development commit">
+        <img src="https://img.shields.io/badge/🚧_commit_SHA-{{ commit_sha }}-blue?style=?style=flat">
     </span>
 {%- endif %}

docs/src/conf.py

@@ -25,7 +25,9 @@
 import os
 from pathlib import Path
 import re
+from subprocess import run
 import sys
+from urllib.parse import quote
 import warnings
 
 
@@ -42,11 +44,21 @@ def autolog(message):
 
 # This is the rtd reference to the version, such as: latest, stable, v3.0.1 etc
 rtd_version = os.environ.get("READTHEDOCS_VERSION")
+if rtd_version is not None:
+    # Make rtd_version safe for use in shields.io badges.
+    rtd_version = rtd_version.replace("_", "__")
+    rtd_version = rtd_version.replace("-", "--")
+    rtd_version = quote(rtd_version)
+
+# branch, tag, external (for pull request builds), or unknown.
+rtd_version_type = os.environ.get("READTHEDOCS_VERSION_TYPE")
 
 # For local testing purposes we can force being on RTD and the version
 # on_rtd = True           # useful for testing
 # rtd_version = "latest"  # useful for testing
 # rtd_version = "stable"  # useful for testing
+# rtd_version_type = "tag"  # useful for testing
+# rtd_version = "my_branch"   # useful for testing
 
 if on_rtd:
     autolog("Build running on READTHEDOCS server")
@@ -85,10 +97,7 @@ def autolog(message):
 
 # The version info for the project you're documenting, acts as replacement for
 # |version|, also used in various other places throughout the built documents.
-
 version = get_version("scitools-iris")
-if version.endswith("+dirty"):
-    version = version[: -len("+dirty")]
 release = version
 autolog(f"Iris Version = {version}")
 autolog(f"Iris Release = {release}")
@@ -303,6 +312,9 @@ def _dotv(version):
     "show_toc_level": 1,
 }
 
+rev_parse = run(["git", "rev-parse", "--short", "HEAD"], capture_output=True)
+commit_sha = rev_parse.stdout.decode().strip()
+
 html_context = {
     # pydata_theme
     "github_repo": "iris",
@@ -312,9 +324,11 @@ def _dotv(version):
     # custom
     "on_rtd": on_rtd,
     "rtd_version": rtd_version,
+    "rtd_version_type": rtd_version_type,
     "version": version,
     "copyright_years": copyright_years,
     "python_version": build_python_version,
+    "commit_sha": commit_sha,
 }
 
 # Add any paths that contain custom static files (such as style sheets) here,

docs/src/whatsnew/3.3.rst

@@ -318,6 +318,9 @@ This document explains the changes made to Iris for this release
 #. `@rcomer`_ and `@wjbenfold`_ (reviewer) used ``pytest`` parametrization to
    streamline the gallery test code. (:pull:`4792`)
 
+#. `@trexfeathers`_ improved settings to better working with
+   ``setuptools_scm``. (:pull:`4925`)
+
 
 .. comment
     Whatsnew author names (@github name) in alphabetical order. Note that,

pyproject.toml

@@ -11,6 +11,7 @@ build-backend = "setuptools.build_meta"
 [tool.setuptools_scm]
 write_to = "lib/iris/_version.py"
 local_scheme = "dirty-tag"
+version_scheme = "release-branch-semver"
 
 [tool.black]
 line-length = 79