diff --git a/.github/workflows/build-docs.yml b/.github/workflows/build-docs.yml index e15ce08c776b..c35c6478d047 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 0450729512cc..c5b2cf873941 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -2,6 +2,7 @@ """ Sphinx documentation for Salt """ + import os import sys import urllib.parse @@ -179,6 +180,7 @@ def _safe_urlsplit(url, scheme="", allow_fragments=True): "salthttpanchors", "saltrepo", "myst_parser", + "sphinx_sitemap", #'saltautodoc', # Must be AFTER autodoc ] @@ -389,6 +391,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 f76170a03f7c..d7db9ec03843 100644 --- a/requirements/static/ci/py3.10/docs.lock +++ b/requirements/static/ci/py3.10/docs.lock @@ -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 diff --git a/requirements/static/ci/py3.11/docs.lock b/requirements/static/ci/py3.11/docs.lock index 736234bf8894..099aa481cc27 100644 --- a/requirements/static/ci/py3.11/docs.lock +++ b/requirements/static/ci/py3.11/docs.lock @@ -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 diff --git a/requirements/static/ci/py3.12/docs.lock b/requirements/static/ci/py3.12/docs.lock index aff19c6c12fb..9e0fc6bd3236 100644 --- a/requirements/static/ci/py3.12/docs.lock +++ b/requirements/static/ci/py3.12/docs.lock @@ -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 diff --git a/requirements/static/ci/py3.13/docs.lock b/requirements/static/ci/py3.13/docs.lock index ba3b136fa76c..ae0f08837f16 100644 --- a/requirements/static/ci/py3.13/docs.lock +++ b/requirements/static/ci/py3.13/docs.lock @@ -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 diff --git a/requirements/static/ci/py3.14/docs.lock b/requirements/static/ci/py3.14/docs.lock index 83044fcf06d7..f2406519dd39 100644 --- a/requirements/static/ci/py3.14/docs.lock +++ b/requirements/static/ci/py3.14/docs.lock @@ -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 diff --git a/requirements/static/ci/py3.9/docs.lock b/requirements/static/ci/py3.9/docs.lock index cba4006337ed..e1dd546f0bc7 100644 --- a/requirements/static/ci/py3.9/docs.lock +++ b/requirements/static/ci/py3.9/docs.lock @@ -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