Repository navigation
Backport libpython docs canonical, sitemap, and noindex fixes to 8.5 - #7784
Merged
cwhite911 merged 5 commits intoJul 28, 2026
Merged
Conversation
…eo#7740) The Sphinx build of the Python library documented every subpackage twice: once under a stripped namespace (pygrass, script, temporal, ...) and once under the full, preferred one (grass.pygrass, grass.script, ...). Keep only the grass.* pages. Drop the seven per-subpackage sphinx-apidoc runs and the sys.path entries in conf.py that made the modules importable under their stripped names, and point the handwritten pages, the theme navigation and the links in doc/ at the grass.* pages and modules. This removes 22 of the 42 Sphinx warnings. All ten "more than one target found for cross-reference" warnings (Table, GrassTestFilesMultiReporter) are gone, since they were caused purely by the duplicate generation, as are the docstring warnings which were reported once per spelling. The three remaining "duplicate object description" warnings (Module, MultiModule, ParallelModuleQueue) are not caused by the stripped namespace: grass.pygrass.modules re-exports these classes, so autodoc documents them both on the package page and on the page of the module defining them. They are left for a separate change. This change was prepared with the assistance of Claude Code. (cherry picked from commit 0b25cf0)
…OSGeo#7760) * docs: Fix libpython canonical and sitemap URLs (OSGeo#5935) conf.py set html_baseurl twice. The second assignment (the bare domain root, added for sphinx-sitemap) overwrote the canonical base, so every libpython page emitted a bare-root canonical, and the sitemap scheme injected the full dev version (grass8.6.0dev), producing 404 URLs. Use a single html_baseurl built from the short numbered prefix (https://grass.osgeo.org/grass<MAJOR><MINOR>/manuals/libpython/) and set the sitemap scheme to "{link}", so canonical and sitemap URLs are identical and resolve to the published grass86 tree. Make merge_sitemaps.py preserve each source sitemap's URLs by default (the --version rewrite is now opt-in) and drop the --version override in documentation.yml, so the merged manuals sitemap keeps grass-stable manuals and grass86 libpython URLs. Add a unit test for check_url_version. Drafted with AI assistance. * docs: Use grass-stable canonical for libpython to match core manuals Per review feedback (OSGeo#7760): keep the stable manuals tree as the absolute canonical base instead of the numbered grassMAJORMINOR tree. This matches the MkDocs core manuals (site_url = .../grass-stable/manuals/) so the merged sitemap is uniformly grass-stable, and leaves dev-URL rewriting to CI. (cherry picked from commit 67a183c)
…o#7772) * docs: noindex development manuals so they defer to grass-stable Dev builds (VERSION micro ends in 'dev') publish under grass-devel/grass86 with pages near-identical to grass-stable. They all canonicalize to grass-stable (see OSGeo#5935), but dev-only pages have no stable equivalent to canonicalize to, so canonical alone can leave them indexed. Emit 'noindex, follow' on dev builds for both generators: - MkDocs: new overrides/main.html gated on extra.noindex, fed by GRASS_DOCS_NOINDEX which documentation.yml sets to true when MICRO ends in 'dev'. - Sphinx: conf.py sets grass_noindex from the version and passes it via html_context to layout.html.template. Stable and release builds leave the flag off and stay indexable. * docs: fix MkDocs noindex flag on dev builds mkdocs !ENV coerces the value to a boolean, so the == "true" test never matched. * man: install mkdocs overrides/main.html into the docs dir The build copies mkdocs files individually, so the new override was missing from MKDOCS_DIR and dev pages got no noindex. (cherry picked from commit 0163d24)
) CI: drop libpython sitemap after merging into the manuals sitemap Its URLs are already in the merged sitemap; remove it so each URL is listed once. (cherry picked from commit 8ff9ef6)
(cherry picked from commit 94f43ae)
github-actions
Bot
added
CI
echoix
approved these changes
Jul 27, 2026
neteler
approved these changes
Jul 28, 2026
neteler
left a comment
neteler
left a comment
Member
There was a problem hiding this comment.
While I cannot fully judge this PR - let's try!
Contributor
Author
|
Was the OSGeo4w failure expected? |
Member
Yes they all fail there, since they don’t exist on the hardcoded server |
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
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
Backport of the libpython/manuals SEO pipeline to
releasebranch_8_5, which builds the published grass-stable docs. Cherry-picks (-x) of the five merged PRs, in merge order:grassnamespacereleasebranch_*, not the version microWhy
The grass-stable docs are built from this branch and are currently broken: libpython canonicals point at grass-devel and the merged sitemap locs are
grass8.5.1dev/...(404), because #7760 only landed onmain. This restores the correct grass-stable canonical and sitemap here.#7772and#7782are backported together on purpose:#7772alone gated noindex onMICRO == *dev, and this branch is8.5.1dev, so it would have wrongly set grass-stable to noindex.#7782's!startsWith(github.ref_name, 'releasebranch_')gate resolves to indexed onreleasebranch_8_5, which is the intended behavior.Conflicts
Only #7740 conflicted (this branch predates its conf.py restructure); resolved in
doc/python_intro.mdby taking the grass-namespace links. The other four applied cleanly on top.Verification
conf.pycompiles; singlehtml_baseurl = .../grass-stable/manuals/libpython/;sitemap_url_scheme = "{link}".utils/test_merge_sitemaps.pypasses (5).GRASS_DOCS_NOINDEXresolves totrueand the PR artifact will show noindex on stable pages. That is expected for a PR build and is NOT how the deployed branch behaves; the realreleasebranch_8_5push build (ref starts withreleasebranch_) resolves to indexed. Verify the canonical + sitemap fixes from the artifact, and the indexed behavior on the post-merge branch build.Once merged, the
backport to 8.5label can be removed from the source PRs.