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,21 @@
 {% 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>
     {% else %}
-        <span title="old version (not stable or latest)">
-            <img src="https://img.shields.io/badge/old_version-{{ version }}-red?style=?style=flat">
+        {# Covers builds for any specific versions/commits, 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>
     {% endif %}
 {%- else %}
     {# not on rtd #}
     <span title="development version">
-        <img src="https://img.shields.io/badge/dev_version-{{ version }}-blue?style=?style=flat">
+        <img src="https://img.shields.io/badge/✏️_version_(dev)-{{ version }}-blue?style=?style=flat">
     </span>
 {%- endif %}

docs/src/conf.py

@@ -85,10 +85,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}")

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