DOCS: Add sitemap support (#7100)

tkknight · bjlittle · web-flow · commit fe718abcb317 · 2026-05-29T18:13:14.000+01:00
* added sitemap support

* update lock files

* add whatsnew

* update sitemap options

* update llms config

* update lock files

* update config for sitemap

* change fetch-depth for checkout

* logic so sitemap only created on stable and latest when on read the docs

* ensure the lastmod is shown on the sitemap.xml

---------

Co-authored-by: Bill Little &lt;bill.james.little@gmail.com&gt;
diff --git a/.github/workflows/ci-tests.yml b/.github/workflows/ci-tests.yml
@@ -57,6 +57,8 @@ jobs:
     steps:
       - name: "checkout"
         uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
 
       - name: "environment configure"
         env:
diff --git a/docs/src/conf.py b/docs/src/conf.py
@@ -191,6 +191,34 @@ def _dotv(version):
     llms_txt_full_build = True
     llms_txt_description = "A powerful, format-agnostic, community-driven Python package for analysing and visualising Earth science data"
 
+# -- sphinx-sitemap ----------------------------------------------------------
+# See https://sphinx-sitemap.readthedocs.io/en/latest/index.html
+
+if on_rtd and rtd_version in ["latest", "stable"]:
+    extensions.append("sphinx_sitemap")
+
+    html_baseurl = f"https://scitools-iris.readthedocs.io/en/{rtd_version}/"
+    autolog(
+        "[READTHEDOCS] [sphinx_sitemap] {} = {}".format("html_baseurl", html_baseurl)
+    )
+
+    sitemap_show_lastmod = True
+    sitemap_url_scheme = "{link}"
+    sitemap_excludes = [
+        "search.html",
+        "genindex.html",
+        "_modules/*",
+        "py-modindex.html",
+        "*/sg_execution_times.html",
+    ]
+else:
+    autolog(
+        (
+            "[sphinx_sitemap] Must be running on READTHEDOCS and version is "
+            "either 'latest' or 'stable', skipping sitemap creation."
+        )
+    )
+
 # -- Napoleon extension -------------------------------------------------------
 # See https://sphinxcontrib-napoleon.readthedocs.io/en/latest/sphinxcontrib.napoleon.html
 napoleon_google_docstring = True
diff --git a/docs/src/whatsnew/latest.rst b/docs/src/whatsnew/latest.rst
@@ -83,6 +83,8 @@ This document explains the changes made to Iris for this release
 #. `@tkknight`_ added a dependency named sphinx-llm to generate summaries
    that LLMs can understand, `llms.txt` and `llms-full.txt`.  (:pull:`7105`)
 
+#. `@tkknight`_ added a dependency named sphinx-sitemap to generate sitemap.xml for
+   the documentaiton. (:pull:`7100`)
 
 📚 Documentation
 ================
@@ -104,6 +106,8 @@ This document explains the changes made to Iris for this release
 #. `@tkknight`_ updated the documentation to generate summaries
    that LLMs can understand, `llms.txt` and `llms-full.txt`. (:pull:`7105`)
 
+#. `@tkknight`_ updated the documentation to generate a sitemap.xml files for the
+   stable version. (:pull:`7100`)
 
 💼 Internal
 ===========
diff --git a/requirements/locks/py312-linux-64.lock b/requirements/locks/py312-linux-64.lock
@@ -1,6 +1,6 @@
 # Generated by conda-lock.
 # platform: linux-64
-# input_hash: be9ecc9d4c44874b248e3aaff15931addc681ac5e520254ba22927b18cfa46e4
+# input_hash: 4a3d484b5967378d5ea2d7056e734cefe5d2b15b9fef363a6dde97daca078cce
 @EXPLICIT
 https://conda.anaconda.org/conda-forge/linux-64/eigen-abi-3.4.0.100-h3bcb7cf_2.conda#aca8e2d59adae20b4715ab372b8d9b9f
 https://conda.anaconda.org/conda-forge/noarch/font-ttf-dejavu-sans-mono-2.37-hab24e00_0.tar.bz2#0c96522c6bdaed4b1566d11387caaf45
@@ -183,7 +183,7 @@ https://conda.anaconda.org/conda-forge/linux-64/multidict-6.7.1-py312h8a5da7c_0.
 https://conda.anaconda.org/conda-forge/noarch/munkres-1.1.4-pyhd8ed1ab_1.conda#37293a85a0f4f77bbd9cf7aaefc62609
 https://conda.anaconda.org/conda-forge/linux-64/openjpeg-2.5.4-h55fea9a_0.conda#11b3379b191f63139e29c0d19dee24cd
 https://conda.anaconda.org/conda-forge/noarch/packaging-26.2-pyhc364b38_0.conda#4c06a92e74452cfa53623a81592e8934
-https://conda.anaconda.org/conda-forge/noarch/platformdirs-4.9.6-pyhcf101f3_0.conda#89c0b6d1793601a2a3a3f7d2d3d8b937
+https://conda.anaconda.org/conda-forge/noarch/platformdirs-4.10.0-pyhcf101f3_0.conda#2c5ef45db85d34799771629bd5860fd7
 https://conda.anaconda.org/conda-forge/noarch/pluggy-1.6.0-pyhf9edf01_1.conda#d7585b6550ad04c8c5e21097ada2888e
 https://conda.anaconda.org/conda-forge/linux-64/propcache-0.3.1-py312h178313f_0.conda#0cf580c1b73146bb9ff1bbdb4d4c8cf9
 https://conda.anaconda.org/conda-forge/linux-64/psutil-7.2.2-py312h5253ce2_0.conda#dd94c506b119130aef5a9382aed648e7
@@ -249,7 +249,7 @@ https://conda.anaconda.org/conda-forge/noarch/partd-1.4.2-pyhd8ed1ab_0.conda#0ba
 https://conda.anaconda.org/conda-forge/linux-64/pillow-12.2.0-py312h50c33e8_0.conda#9e5609720e31213d4f39afe377f6217e
 https://conda.anaconda.org/conda-forge/linux-64/proj-9.7.1-he0df7b0_3.conda#031e33ae075b336c0ce92b14efa886c5
 https://conda.anaconda.org/conda-forge/noarch/python-dateutil-2.9.0.post0-pyhe01879c_2.conda#5b8d21249ff20967101ffa321cab24e8
-https://conda.anaconda.org/conda-forge/noarch/python-discovery-1.3.1-pyhcf101f3_0.conda#45ea5eceb1c2e35a08a834869837a090
+https://conda.anaconda.org/conda-forge/noarch/python-discovery-1.4.0-pyhcf101f3_0.conda#fb1e5c138e2d933e59b3fa0462acc5e6
 https://conda.anaconda.org/conda-forge/noarch/python-gil-3.12.13-hd8ed1ab_0.conda#32780d6794b8056b78602103a04e90ef
 https://conda.anaconda.org/conda-forge/noarch/typing-extensions-4.15.0-h396c80c_0.conda#edd329d7d3a4ab45dcf905899a7a6115
 https://conda.anaconda.org/conda-forge/noarch/vcs_versioning-1.1.1-pyhd8ed1ab_0.conda#d3874a78e238013db5106c8e31f1ae58
@@ -348,6 +348,8 @@ https://conda.anaconda.org/conda-forge/noarch/sphinx-copybutton-0.5.2-pyhd8ed1ab
 https://conda.anaconda.org/conda-forge/noarch/sphinx-data-viewer-0.1.5-pyhd8ed1ab_1.conda#fbe6437c6899c54e52f9258518035aca
 https://conda.anaconda.org/conda-forge/noarch/sphinx-design-0.7.0-pyhd8ed1ab_0.conda#28eddfb8b9ecdd044a6f609f985398a7
 https://conda.anaconda.org/conda-forge/noarch/sphinx-gallery-0.21.0-pyhd8ed1ab_0.conda#9b783047bd5bef0998f129bef8fad477
+https://conda.anaconda.org/conda-forge/noarch/sphinx-last-updated-by-git-0.3.8-pyhe01879c_0.conda#405a232fb900fc631d2f1b5cdf01dea9
+https://conda.anaconda.org/conda-forge/noarch/sphinx-sitemap-2.9.0-pyhcf101f3_0.conda#3baeff262222dc87e978a68702bc5797
 https://conda.anaconda.org/conda-forge/noarch/sphinx-markdown-builder-0.6.10-pyhd8ed1ab_0.conda#e804fed0abd0c8df4ff40e3084d724a0
 https://conda.anaconda.org/conda-forge/noarch/sphinx-llm-0.4.1-pyhcf101f3_0.conda#47b4654f4d7dabd83341ca3ef7915c9c
 https://conda.anaconda.org/conda-forge/noarch/sphinx-reredirects-1.1.0-pyhd8ed1ab_0.conda#8392493ce6fbb8ab72a101af8e8a5d03
diff --git a/requirements/locks/py313-linux-64.lock b/requirements/locks/py313-linux-64.lock
@@ -1,6 +1,6 @@
 # Generated by conda-lock.
 # platform: linux-64
-# input_hash: 0484641f4d6c1511958c74f00dde6f3ddb12f7c77708e2a3cd87565005c1ebda
+# input_hash: e8cc875fa4a3e95a582acab1fdcdd7c54a9f9b859fc62732470e4d85de5f2f9c
 @EXPLICIT
 https://conda.anaconda.org/conda-forge/linux-64/eigen-abi-3.4.0.100-h3bcb7cf_2.conda#aca8e2d59adae20b4715ab372b8d9b9f
 https://conda.anaconda.org/conda-forge/noarch/font-ttf-dejavu-sans-mono-2.37-hab24e00_0.tar.bz2#0c96522c6bdaed4b1566d11387caaf45
@@ -185,7 +185,7 @@ https://conda.anaconda.org/conda-forge/noarch/munkres-1.1.4-pyhd8ed1ab_1.conda#3
 https://conda.anaconda.org/conda-forge/linux-64/openjpeg-2.5.4-h55fea9a_0.conda#11b3379b191f63139e29c0d19dee24cd
 https://conda.anaconda.org/conda-forge/noarch/packaging-26.2-pyhc364b38_0.conda#4c06a92e74452cfa53623a81592e8934
 https://conda.anaconda.org/conda-forge/noarch/pip-26.1.1-pyh145f28c_0.conda#2e7e59a063366f1fc4f45ac86bd9485f
-https://conda.anaconda.org/conda-forge/noarch/platformdirs-4.9.6-pyhcf101f3_0.conda#89c0b6d1793601a2a3a3f7d2d3d8b937
+https://conda.anaconda.org/conda-forge/noarch/platformdirs-4.10.0-pyhcf101f3_0.conda#2c5ef45db85d34799771629bd5860fd7
 https://conda.anaconda.org/conda-forge/noarch/pluggy-1.6.0-pyhf9edf01_1.conda#d7585b6550ad04c8c5e21097ada2888e
 https://conda.anaconda.org/conda-forge/linux-64/propcache-0.3.1-py313h8060acc_0.conda#b62867739241368f43f164889b45701b
 https://conda.anaconda.org/conda-forge/linux-64/psutil-7.2.2-py313h54dd161_0.conda#25fe6e02c2083497b3239e21b49d8093
@@ -251,7 +251,7 @@ https://conda.anaconda.org/conda-forge/noarch/pbr-7.0.3-pyhd8ed1ab_0.conda#d312c
 https://conda.anaconda.org/conda-forge/linux-64/pillow-12.2.0-py313h80991f8_0.conda#7245f1bbf52ed5e3818d742f51b44a7d
 https://conda.anaconda.org/conda-forge/linux-64/proj-9.7.1-he0df7b0_3.conda#031e33ae075b336c0ce92b14efa886c5
 https://conda.anaconda.org/conda-forge/noarch/python-dateutil-2.9.0.post0-pyhe01879c_2.conda#5b8d21249ff20967101ffa321cab24e8
-https://conda.anaconda.org/conda-forge/noarch/python-discovery-1.3.1-pyhcf101f3_0.conda#45ea5eceb1c2e35a08a834869837a090
+https://conda.anaconda.org/conda-forge/noarch/python-discovery-1.4.0-pyhcf101f3_0.conda#fb1e5c138e2d933e59b3fa0462acc5e6
 https://conda.anaconda.org/conda-forge/noarch/python-gil-3.13.13-h4df99d1_100.conda#fd00e4b24ea88093c93f5c9bad27b52f
 https://conda.anaconda.org/conda-forge/noarch/typing-extensions-4.15.0-h396c80c_0.conda#edd329d7d3a4ab45dcf905899a7a6115
 https://conda.anaconda.org/conda-forge/noarch/vcs_versioning-1.1.1-pyhd8ed1ab_0.conda#d3874a78e238013db5106c8e31f1ae58
@@ -347,6 +347,8 @@ https://conda.anaconda.org/conda-forge/noarch/sphinx-copybutton-0.5.2-pyhd8ed1ab
 https://conda.anaconda.org/conda-forge/noarch/sphinx-data-viewer-0.1.5-pyhd8ed1ab_1.conda#fbe6437c6899c54e52f9258518035aca
 https://conda.anaconda.org/conda-forge/noarch/sphinx-design-0.7.0-pyhd8ed1ab_0.conda#28eddfb8b9ecdd044a6f609f985398a7
 https://conda.anaconda.org/conda-forge/noarch/sphinx-gallery-0.21.0-pyhd8ed1ab_0.conda#9b783047bd5bef0998f129bef8fad477
+https://conda.anaconda.org/conda-forge/noarch/sphinx-last-updated-by-git-0.3.8-pyhe01879c_0.conda#405a232fb900fc631d2f1b5cdf01dea9
+https://conda.anaconda.org/conda-forge/noarch/sphinx-sitemap-2.9.0-pyhcf101f3_0.conda#3baeff262222dc87e978a68702bc5797
 https://conda.anaconda.org/conda-forge/noarch/sphinx-markdown-builder-0.6.10-pyhd8ed1ab_0.conda#e804fed0abd0c8df4ff40e3084d724a0
 https://conda.anaconda.org/conda-forge/noarch/sphinx-llm-0.4.1-pyhcf101f3_0.conda#47b4654f4d7dabd83341ca3ef7915c9c
 https://conda.anaconda.org/conda-forge/noarch/sphinx-reredirects-1.1.0-pyhd8ed1ab_0.conda#8392493ce6fbb8ab72a101af8e8a5d03
diff --git a/requirements/locks/py314-linux-64.lock b/requirements/locks/py314-linux-64.lock
@@ -1,6 +1,6 @@
 # Generated by conda-lock.
 # platform: linux-64
-# input_hash: a537c7c8fe6f5f86aca711844547774ccf6caaf6f44c81a346995ff339f3880b
+# input_hash: ea822d017c19e4961a0c7ef167e7bf9e9417ece46d1b6c16169ff2d6a6552b98
 @EXPLICIT
 https://conda.anaconda.org/conda-forge/noarch/font-ttf-dejavu-sans-mono-2.37-hab24e00_0.tar.bz2#0c96522c6bdaed4b1566d11387caaf45
 https://conda.anaconda.org/conda-forge/noarch/font-ttf-inconsolata-3.000-h77eed37_0.tar.bz2#34893075a5c9e55cdafac56607368fc6
@@ -162,7 +162,7 @@ https://conda.anaconda.org/conda-forge/noarch/munkres-1.1.4-pyhd8ed1ab_1.conda#3
 https://conda.anaconda.org/conda-forge/linux-64/openjpeg-2.5.4-h55fea9a_0.conda#11b3379b191f63139e29c0d19dee24cd
 https://conda.anaconda.org/conda-forge/noarch/packaging-26.2-pyhc364b38_0.conda#4c06a92e74452cfa53623a81592e8934
 https://conda.anaconda.org/conda-forge/noarch/pip-26.1.1-pyh145f28c_0.conda#2e7e59a063366f1fc4f45ac86bd9485f
-https://conda.anaconda.org/conda-forge/noarch/platformdirs-4.9.6-pyhcf101f3_0.conda#89c0b6d1793601a2a3a3f7d2d3d8b937
+https://conda.anaconda.org/conda-forge/noarch/platformdirs-4.10.0-pyhcf101f3_0.conda#2c5ef45db85d34799771629bd5860fd7
 https://conda.anaconda.org/conda-forge/noarch/pluggy-1.6.0-pyhf9edf01_1.conda#d7585b6550ad04c8c5e21097ada2888e
 https://conda.anaconda.org/conda-forge/linux-64/psutil-7.2.2-py314h0f05182_0.conda#4f225a966cfee267a79c5cb6382bd121
 https://conda.anaconda.org/conda-forge/noarch/pycparser-3.0-pyhcf101f3_0.conda#9c5491066224083c41b6d5635ed7107b
@@ -218,7 +218,7 @@ https://conda.anaconda.org/conda-forge/noarch/pbr-7.0.3-pyhd8ed1ab_0.conda#d312c
 https://conda.anaconda.org/conda-forge/linux-64/pillow-12.2.0-py314h8ec4b1a_0.conda#76c4757c0ec9d11f969e8eb44899307b
 https://conda.anaconda.org/conda-forge/linux-64/proj-9.7.1-he0df7b0_3.conda#031e33ae075b336c0ce92b14efa886c5
 https://conda.anaconda.org/conda-forge/noarch/python-dateutil-2.9.0.post0-pyhe01879c_2.conda#5b8d21249ff20967101ffa321cab24e8
-https://conda.anaconda.org/conda-forge/noarch/python-discovery-1.3.1-pyhcf101f3_0.conda#45ea5eceb1c2e35a08a834869837a090
+https://conda.anaconda.org/conda-forge/noarch/python-discovery-1.4.0-pyhcf101f3_0.conda#fb1e5c138e2d933e59b3fa0462acc5e6
 https://conda.anaconda.org/conda-forge/noarch/python-gil-3.14.5-h4df99d1_100.conda#41954747ba952ec4b01e16c2c9e8d8ff
 https://conda.anaconda.org/conda-forge/noarch/typing-extensions-4.15.0-h396c80c_0.conda#edd329d7d3a4ab45dcf905899a7a6115
 https://conda.anaconda.org/conda-forge/noarch/vcs_versioning-1.1.1-pyhd8ed1ab_0.conda#d3874a78e238013db5106c8e31f1ae58
@@ -291,6 +291,8 @@ https://conda.anaconda.org/conda-forge/noarch/sphinx-copybutton-0.5.2-pyhd8ed1ab
 https://conda.anaconda.org/conda-forge/noarch/sphinx-data-viewer-0.1.5-pyhd8ed1ab_1.conda#fbe6437c6899c54e52f9258518035aca
 https://conda.anaconda.org/conda-forge/noarch/sphinx-design-0.7.0-pyhd8ed1ab_0.conda#28eddfb8b9ecdd044a6f609f985398a7
 https://conda.anaconda.org/conda-forge/noarch/sphinx-gallery-0.21.0-pyhd8ed1ab_0.conda#9b783047bd5bef0998f129bef8fad477
+https://conda.anaconda.org/conda-forge/noarch/sphinx-last-updated-by-git-0.3.8-pyhe01879c_0.conda#405a232fb900fc631d2f1b5cdf01dea9
+https://conda.anaconda.org/conda-forge/noarch/sphinx-sitemap-2.9.0-pyhcf101f3_0.conda#3baeff262222dc87e978a68702bc5797
 https://conda.anaconda.org/conda-forge/noarch/sphinx-markdown-builder-0.6.10-pyhd8ed1ab_0.conda#e804fed0abd0c8df4ff40e3084d724a0
 https://conda.anaconda.org/conda-forge/noarch/sphinx-llm-0.4.1-pyhcf101f3_0.conda#47b4654f4d7dabd83341ca3ef7915c9c
 https://conda.anaconda.org/conda-forge/noarch/sphinx-reredirects-1.1.0-pyhd8ed1ab_0.conda#8392493ce6fbb8ab72a101af8e8a5d03
diff --git a/requirements/py312.yml b/requirements/py312.yml
@@ -60,6 +60,7 @@ dependencies:
   - sphinx-needs
   - sphinx-reredirects
   - sphinx-llm
+  - sphinx-sitemap
 
 # Temporary minimum pins.
 # See https://github.com/SciTools/iris/pull/5051
diff --git a/requirements/py313.yml b/requirements/py313.yml
@@ -60,6 +60,7 @@ dependencies:
   - sphinx-needs
   - sphinx-reredirects
   - sphinx-llm
+  - sphinx-sitemap
 
 # Temporary minimum pins.
 # See https://github.com/SciTools/iris/pull/5051
diff --git a/requirements/py314.yml b/requirements/py314.yml
@@ -60,6 +60,7 @@ dependencies:
   - sphinx-needs
   - sphinx-reredirects
   - sphinx-llm
+  - sphinx-sitemap
 
 # Temporary minimum pins.
 # See https://github.com/SciTools/iris/pull/5051
