saltstack · scriptautomate-bc · Sep 5, 2026 · Sep 5, 2026 · Sep 5, 2026 · Sep 5, 2026
@@ -37,6 +37,9 @@ jobs:
 
     steps:
       - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+        with:
+          fetch-depth: 0
+          filter: blob:none
       - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
         with:
           python-version: '3.14'

@@ -0,0 +1 @@
+Added `<lastmod>` timestamps to the generated docs `sitemap.xml`, sourced from each page's git commit time (and, for autodoc pages, the newest commit among the Python modules that page documents). The docs build job's checkout now fetches full git history (via a blobless clone) since the timestamps cannot be computed from a shallow clone.
@@ -0,0 +1 @@
+Removed the unused, broken `sitemap` target from `doc/Makefile`. It clobbered the extension list (dropping `saltdomain` and autodoc), hardcoded `html_baseurl` to `en/latest/`, and required `sphinx-sitemap`, which was in no requirements or lock file. The docs build now emits a sitemap directly as part of the regular HTML build.
@@ -16,7 +16,7 @@ ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
 # the i18n builder cannot share the environment and doctrees with the others
 I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
 
-.PHONY: help clean check_sphinx-build html dirhtml singlehtml pickle json htmlhelp qthelp devhelp latex latexpdf text man changes linkcheck linkcheck-audit sitemap doctest
+.PHONY: help clean check_sphinx-build html dirhtml singlehtml pickle json htmlhelp qthelp devhelp latex latexpdf text man changes linkcheck linkcheck-audit doctest
 
 help:
 	@echo "Please use \`make <target>' where <target> is one of"
@@ -42,7 +42,6 @@ help:
 	@echo "  pseudoxml  to make pseudoxml-XML files for display purposes"
 	@echo "  linkcheck  to check all external links for integrity"
 	@echo "  linkcheck-audit  to run the wrapped audit (strips the catch-all ignore) and emit a CSV"
-	@echo "  sitemap    to build the HTML output with sphinx-sitemap and emit a sitemap.xml"
 	@echo "  doctest    to run all doctests embedded in the documentation (if enabled)"
 
 clean:
@@ -182,13 +181,6 @@ linkcheck-audit:
 	@echo
 	@echo "Link audit complete; CSV report at $(BUILDDIR)/linkcheck-audit/report.csv."
 
-sitemap: check_sphinx-build
-	$(SPHINXBUILD) -b html -D extensions=sphinx_sitemap \
-	    -D html_baseurl=https://docs.saltproject.io/en/latest/ \
-	    $(ALLSPHINXOPTS) $(BUILDDIR)/sitemap
-	@echo
-	@echo "Sitemap generated under $(BUILDDIR)/sitemap/sitemap.xml."
-
 doctest: check_sphinx-build
 	$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
 	@echo "Testing of doctests in the sources finished, look at the " \

@@ -179,6 +179,7 @@ def _safe_urlsplit(url, scheme="", allow_fragments=True):
     "salthttpanchors",
     "saltrepo",
     "myst_parser",
+    "sphinx_sitemap",
     #'saltautodoc', # Must be AFTER autodoc
 ]
 
@@ -389,6 +390,20 @@ def _safe_urlsplit(url, scheme="", allow_fragments=True):
 html_show_sphinx = True
 html_show_copyright = True
 
+# Deployed URL segment: /en/<major>/ for release branches, /en/master/ for master.
+# WEBSITE_RELEASE is already set correctly by every builddocs job; major_version
+# (line 89) is the right default, which keeps this merge-forward safe with no per-branch edits.
+docs_url_segment = os.environ.get("WEBSITE_RELEASE", major_version)
+html_baseurl = f"https://docs.saltproject.io/en/{docs_url_segment}/"
+sitemap_url_scheme = "{link}"  # segment already in html_baseurl
+sitemap_locales = [None]
+sitemap_show_lastmod = not building_man_only  # max(rst commit time, autodoc'd .py commit times)
+# Skipped for man-only builds: sphinx-last-updated-by-git runs a git log against
+# every page's dependencies, and CI jobs that only build man pages (e.g. the
+# release-patch step in ci.yml) use a shallow checkout, which turns into a hard
+# "git.too_shallow" failure under -W. Man pages have no sitemap consumer anyway.
+sitemap_excludes = ["search.html", "genindex.html", "http-routingtable.html"]
+
 ### Latex options
 
 latex_documents = [

@@ -5,6 +5,7 @@ myst-docutils[linkify]
 sphinxcontrib-httpdomain>=1.8.1,<2.0.0; python_version < '3.10'
 sphinxcontrib-httpdomain>=2.0.0; python_version >= '3.10'
 sphinxcontrib-spelling
+sphinx-sitemap>=2.9.0
 cherrypy
 jinja2
 pydata-sphinx-theme

@@ -319,8 +319,13 @@ sphinx==7.0.1
     # via
     #   -r requirements/static/ci/docs.txt
     #   pydata-sphinx-theme
+    #   sphinx-last-updated-by-git
     #   sphinxcontrib-httpdomain
     #   sphinxcontrib-spelling
+sphinx-last-updated-by-git==0.3.8
+    # via sphinx-sitemap
+sphinx-sitemap==2.9.0
+    # via -r requirements/static/ci/docs.txt
 sphinxcontrib-applehelp==1.0.4
     # via sphinx
 sphinxcontrib-devhelp==1.0.2

@@ -314,8 +314,13 @@ sphinx==7.0.1
     # via
     #   -r requirements/static/ci/docs.txt
     #   pydata-sphinx-theme
+    #   sphinx-last-updated-by-git
     #   sphinxcontrib-httpdomain
     #   sphinxcontrib-spelling
+sphinx-last-updated-by-git==0.3.8
+    # via sphinx-sitemap
+sphinx-sitemap==2.9.0
+    # via -r requirements/static/ci/docs.txt
 sphinxcontrib-applehelp==1.0.4
     # via sphinx
 sphinxcontrib-devhelp==1.0.2

@@ -312,8 +312,13 @@ sphinx==9.1.0
     # via
     #   -r requirements/static/ci/docs.txt
     #   pydata-sphinx-theme
+    #   sphinx-last-updated-by-git
     #   sphinxcontrib-httpdomain
     #   sphinxcontrib-spelling
+sphinx-last-updated-by-git==0.3.8
+    # via sphinx-sitemap
+sphinx-sitemap==2.9.0
+    # via -r requirements/static/ci/docs.txt
 sphinxcontrib-applehelp==2.0.0
     # via sphinx
 sphinxcontrib-devhelp==2.0.0

@@ -310,8 +310,13 @@ sphinx==9.1.0
     # via
     #   -r requirements/static/ci/docs.txt
     #   pydata-sphinx-theme
+    #   sphinx-last-updated-by-git
     #   sphinxcontrib-httpdomain
     #   sphinxcontrib-spelling
+sphinx-last-updated-by-git==0.3.8
+    # via sphinx-sitemap
+sphinx-sitemap==2.9.0
+    # via -r requirements/static/ci/docs.txt
 sphinxcontrib-applehelp==2.0.0
     # via sphinx
 sphinxcontrib-devhelp==2.0.0

@@ -312,8 +312,13 @@ sphinx==9.1.0
     # via
     #   -r requirements/static/ci/docs.txt
     #   pydata-sphinx-theme
+    #   sphinx-last-updated-by-git
     #   sphinxcontrib-httpdomain
     #   sphinxcontrib-spelling
+sphinx-last-updated-by-git==0.3.8
+    # via sphinx-sitemap
+sphinx-sitemap==2.9.0
+    # via -r requirements/static/ci/docs.txt
 sphinxcontrib-applehelp==2.0.0
     # via sphinx
 sphinxcontrib-devhelp==2.0.0

@@ -323,8 +323,13 @@ sphinx==7.0.1
     # via
     #   -r requirements/static/ci/docs.txt
     #   pydata-sphinx-theme
+    #   sphinx-last-updated-by-git
     #   sphinxcontrib-httpdomain
     #   sphinxcontrib-spelling
+sphinx-last-updated-by-git==0.3.8
+    # via sphinx-sitemap
+sphinx-sitemap==2.9.0
+    # via -r requirements/static/ci/docs.txt
 sphinxcontrib-applehelp==1.0.4
     # via sphinx
 sphinxcontrib-devhelp==1.0.2
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1 @@
		Added `<lastmod>` timestamps to the generated docs `sitemap.xml`, sourced from each page's git commit time (and, for autodoc pages, the newest commit among the Python modules that page documents). The docs build job's checkout now fetches full git history (via a blobless clone) since the timestamps cannot be computed from a shallow clone.
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1 @@
		Removed the unused, broken `sitemap` target from `doc/Makefile`. It clobbered the extension list (dropping `saltdomain` and autodoc), hardcoded `html_baseurl` to `en/latest/`, and required `sphinx-sitemap`, which was in no requirements or lock file. The docs build now emits a sitemap directly as part of the regular HTML build.