[cwhite911]

Fixes #5935

Problem

python/grass/docs/conf.py assigned html_baseurl twice to conflicting values. Both sphinx-sitemap and Sphinx's own canonical-link generation read that single variable, so the last assignment won for both:

• conf.py canonical base (correct): .../grass-stable/manuals/libpython/
• re-set for the sitemap root (wins): https://grass.osgeo.org/, with sitemap_url_scheme = "grass{version}manuals/libpython/{link}" where {version} = the full dev string 8.6.0dev.

Live result: every libpython page emitted <link rel="canonical" href="https://grass.osgeo.org/exceptions.html"> (bare root), and grass-devel/manuals/libpython/sitemap.xml listed https://grass.osgeo.org/grass8.6.0dev/manuals/libpython/... (404). The merge step then re-stamped the merged manuals sitemap to the numeric VERSION, breaking it too.

Fix

Per the direction in the issue thread (URLs should be grass86, i.e. the numbered grass<MAJOR><MINOR> tree, which serves 200):

• conf.py: derive a short grass<MAJOR><MINOR> prefix from core.version() and use a single html_baseurl = https://grass.osgeo.org/grass86/manuals/libpython/. Set sitemap_url_scheme = "{link}" so each sitemap <loc> equals the canonical URL exactly and resolves to the published numbered tree. No dependency on the full dev version string.
• utils/merge_sitemaps.py: make the version rewrite opt-in (--version defaults to None); when omitted, each source sitemap keeps its own prefix. Adds a unit test for check_url_version.
• documentation.yml: drop the --version "${VERSION}" override so the merged manuals/sitemap.xml keeps grass-stable core-manual URLs and grass86 libpython URLs (each matching its own canonical).

Scope is intentionally libpython (Sphinx) only; the MkDocs core manuals stay on their current grass-stable canonical.

Verification

• pytest utils/test_merge_sitemaps.py (5 passing): preserve when no version, rewrite when a version is given.
• Manual merge runs confirm preserve (grass-stable manuals + grass86 libpython) and explicit---version rewrite.
• Version derivation: 8.6.0dev/8.6.0 -> grass86, 8.10.0dev -> grass810.
• pre-commit (ruff, flake8, yamllint, zizmor, codespell) passes.
• Left as draft so the documentation.yml CI can build the docs and the generated libpython/sitemap.xml + a page canonical can be checked end-to-end.

Drafted with AI assistance.

[cwhite911]

So the build artifact for the merged site now looks correct for the libpython, but the manuals look off. Shouldn't they be grass-devel?

<url>
      <loc>https://grass.osgeo.org/grass-stable/manuals/command_line_intro.html</loc>
      <lastmod>2026-07-18</lastmod>
</url>
<loc>https://grass.osgeo.org/grass86/manuals/libpython/grass.app.html</loc>

[neteler]

Oh, a tricky one!

[wenzeslaus]

Development vs stable links: My idea was to keep stable links when absolute URL is needed and replace in CI for dev (not implemented, there is a PR). CI could use relative links.

[cwhite911]

Agreed on keeping stable as the absolute base. I switched the libpython canonical to https://grass.osgeo.org/grass-stable/manuals/libpython/ so it matches what the MkDocs manuals already do (site_url is grass-stable and isn't overridden per build). Now every version build (grass-devel, grass-stable, and the numbered versions) canonicalizes to grass-stable, and the merged sitemap is uniformly grass-stable instead of the grass-stable/grass86 mix from before.

The one case this doesn't fully resolve is the dev tree: a page that's new in 8.6 and not yet in 8.5 will canonical to a grass-stable URL that 404s. I'd rather not fix that by rewriting the canonical for dev, since then dev competes with stable in search again, which is the thing the canonical is there to prevent. The cleaner path is noindex, follow on the whole dev tree (a per-build flag when VERSION ends in dev), applied to both the MkDocs overrides and the Sphinx head so the two stay consistent. That's compatible with the relative-links or CI-rewrite idea, but noindex is the smaller change and avoids putting noindex and a cross-version canonical on the same page.