From a030307632751ea95f4b7ac6f07d32fbf19cc43e Mon Sep 17 00:00:00 2001 From: Andrew Lamb Date: Tue, 27 Oct 2026 16:11:35 -0400 Subject: [PATCH] docs: do not emit canonical links or sitemap for versioned release docs Release documentation published under /versions// currently declares every page as its own canonical URL and ships its own sitemap.xml, so search engines see each versioned copy as a competing page. Only the development docs at the site root should be indexed. Clear html_baseurl in the release overlay so Sphinx emits no tag, and drop sphinx-sitemap from release builds. Co-Authored-By: Claude Fable 5.1 --- dev/release/README.md | 7 ++----- docs/scripts/release/conf.py | 18 ++++++++++++------ 2 files changed, 14 insertions(+), 11 deletions(-) diff --git a/dev/release/README.md b/dev/release/README.md index 477e01a068a33..61d19471a6fe0 100644 --- a/dev/release/README.md +++ b/dev/release/README.md @@ -326,14 +326,11 @@ git worktree add --detach /tmp/datafusion-55.0.0 55.0.0 cd /tmp/datafusion-55.0.0/docs DATAFUSION_DOCS_SOURCE="$PWD/source" DATAFUSION_DOCS_VERSION=55.0.0 \ SPHINXOPTS="-W -c $DATAFUSION_DOCS_OVERLAY" \ - uv run --package datafusion-docs --with sphinx-sitemap ./build.sh + uv run --package datafusion-docs ./build.sh cd - ``` -Notes: - -1. You need to use an absolute path to the overlay in your current checkout. -2. The `--with sphinx-sitemap` option supplies the sitemap extension for older tags. +Note: you need to use an absolute path to the overlay in your current checkout. To preview the result, build the docs from your main checkout (`uv run --package datafusion-docs ./build.sh` in `docs/`), copy the release diff --git a/docs/scripts/release/conf.py b/docs/scripts/release/conf.py index 8776449cb9711..5bf1aeaa560f7 100644 --- a/docs/scripts/release/conf.py +++ b/docs/scripts/release/conf.py @@ -20,8 +20,8 @@ Loads ``conf.py`` from a``docs/source`` directory located at ``DATAFUSION_DOCS_SOURCE`` and overrides the following settings: - the version string (``DATAFUSION_DOCS_VERSION``), -- the site base URL used for the sitemap -- the version switcher. +- the version switcher, +- the sitemap and canonical URL (both disabled, see below). Why? @@ -52,10 +52,16 @@ html_favicon = str(source / html_favicon) version = release = os.environ["DATAFUSION_DOCS_VERSION"] -html_baseurl = f"https://datafusion.apache.org/versions/{version}/" -sitemap_url_scheme = "{link}" -if "sphinx_sitemap" not in extensions: - extensions.append("sphinx_sitemap") + +# Only the development documentation at the site root should be indexed by +# search engines. Sphinx emits a `` tag on every page +# when `html_baseurl` is set, and sphinx-sitemap uses the same setting to +# write `sitemap.xml`. With the tag's `html_baseurl` each versioned page would +# declare itself canonical and compete with the root copy of the same page, +# so clear it and skip the sitemap for release builds. The root `robots.txt` +# only references the root `sitemap.xml`. +html_baseurl = "" +extensions = [ext for ext in extensions if ext != "sphinx_sitemap"] html_context = {**html_context, "github_repo": "datafusion", "github_version": version} html_theme_options = { **html_theme_options,