feat(docs): add git-derived lastmod to sitemap, and include in docs bundles uploaded to release assets - #70240
Draft
scriptautomate-bc wants to merge 5 commits into
Draft
Conversation
Add sphinx-sitemap to the docs extensions and requirements, and set html_baseurl/sitemap_show_lastmod so every emitted page gets a <lastmod> sourced from git commit time. autodoc-registered .py module dependencies are picked up automatically via sphinx-last-updated-by-git, so a docstring or signature edit correctly bumps the rendered page's lastmod. The URL segment is keyed off WEBSITE_RELEASE (falling back to major_version), which every builddocs job already sets correctly, so this needs no per-branch edits on merge-forward.
The build job's checkout was depth-1, which causes sphinx-last-updated-by-git to either fail the build under -W or silently emit sitemap entries with no lastmod. Use fetch-depth: 0 with a blobless filter to keep the clone cheap while preserving commit history.
It clobbers the extension list (dropping saltdomain and autodoc), hardcodes html_baseurl to en/latest/, and needs sphinx-sitemap, which was in no requirements or lock file. It is superseded by the sitemap now generated as part of the regular html build.
scriptautomate-bc
changed the title
sphinx-last-updated-by-git runs a git log against every page's dependencies whenever sitemap_show_lastmod is enabled, regardless of builder. CI jobs that only build man pages (e.g. the release-patch step in ci.yml's prepare-release job) use a shallow checkout, so this turned into a hard "git.too_shallow" failure under -W, which cascaded into the docs build jobs failing since they never got their release-patch artifact. Man pages have no sitemap consumer, so skip lastmod there instead of widening every man-page-generating job's checkout.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What does this PR do?
Basic sitemap improvements across the docs to assist with AI agent or search engine crawlers for understanding when certain docs have last been updated.
sitemap index isn't currently generated/saved for each set of documentation. sitemaps are currently available for other subsets of docs:
But not for the salt reference docs:
This is meant to go into 3006.x, then be merge-forwarded -> 3008.x -> master
Related efforts:
What issues does this PR fix or reference?
Previous Behavior
No sitemap is included in docs bundles in release assets.
New Behavior
Generate sitemap in the docs bundle, and include last updated timestamps, so builddocs deployment includes sitemap data.
Merge requirements satisfied?
[NOTICE] Bug fixes or features added to Salt require tests.