diff --git a/.github/workflows/build-docs.yml b/.github/workflows/build-docs.yml index 9a252819e6aa..6358eb26f31e 100644 --- a/.github/workflows/build-docs.yml +++ b/.github/workflows/build-docs.yml @@ -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' diff --git a/changelog/70241.added.md b/changelog/70241.added.md new file mode 100644 index 000000000000..98a1aa45d434 --- /dev/null +++ b/changelog/70241.added.md @@ -0,0 +1 @@ +Added `` 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. diff --git a/changelog/70241.removed.md b/changelog/70241.removed.md new file mode 100644 index 000000000000..b7634aed78fa --- /dev/null +++ b/changelog/70241.removed.md @@ -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. diff --git a/doc/Makefile b/doc/Makefile index 5aa4dd9e21d2..81db03b255eb 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -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 ' where 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 " \ diff --git a/doc/conf.py b/doc/conf.py index c944f58dcb5d..995a194c93cf 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -2,6 +2,7 @@ """ Sphinx documentation for Salt """ + import os import sys import urllib.parse @@ -186,6 +187,7 @@ def _safe_urlsplit(url, scheme="", allow_fragments=True): "salthttpanchors", "saltrepo", "myst_parser", + "sphinx_sitemap", #'saltautodoc', # Must be AFTER autodoc ] @@ -403,6 +405,22 @@ def _safe_urlsplit(url, scheme="", allow_fragments=True): html_show_sphinx = True html_show_copyright = True +# Deployed URL segment: /en// 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 = [ diff --git a/requirements/static/ci/docs.txt b/requirements/static/ci/docs.txt index c75fb3aa0477..6d0b36ac5739 100644 --- a/requirements/static/ci/docs.txt +++ b/requirements/static/ci/docs.txt @@ -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 diff --git a/requirements/static/ci/py3.10/docs.lock b/requirements/static/ci/py3.10/docs.lock index a2bcc01fde49..3a5f60de99d1 100644 --- a/requirements/static/ci/py3.10/docs.lock +++ b/requirements/static/ci/py3.10/docs.lock @@ -359,8 +359,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 diff --git a/requirements/static/ci/py3.11/docs.lock b/requirements/static/ci/py3.11/docs.lock index 1a780076747c..4d686f2d346e 100644 --- a/requirements/static/ci/py3.11/docs.lock +++ b/requirements/static/ci/py3.11/docs.lock @@ -354,8 +354,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 diff --git a/requirements/static/ci/py3.12/docs.lock b/requirements/static/ci/py3.12/docs.lock index 3bb7f815125d..cd555abab83a 100644 --- a/requirements/static/ci/py3.12/docs.lock +++ b/requirements/static/ci/py3.12/docs.lock @@ -352,8 +352,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 diff --git a/requirements/static/ci/py3.13/docs.lock b/requirements/static/ci/py3.13/docs.lock index bfbe0bafb14b..1c884205e47b 100644 --- a/requirements/static/ci/py3.13/docs.lock +++ b/requirements/static/ci/py3.13/docs.lock @@ -350,8 +350,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 diff --git a/requirements/static/ci/py3.14/docs.lock b/requirements/static/ci/py3.14/docs.lock index 8660baeeb199..d25d3d319314 100644 --- a/requirements/static/ci/py3.14/docs.lock +++ b/requirements/static/ci/py3.14/docs.lock @@ -350,8 +350,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 diff --git a/requirements/static/ci/py3.9/docs.lock b/requirements/static/ci/py3.9/docs.lock index 7f70637a8a63..c091aa129585 100644 --- a/requirements/static/ci/py3.9/docs.lock +++ b/requirements/static/ci/py3.9/docs.lock @@ -363,8 +363,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