From 9e3235e81fb5ed256e88f53cbe2ecec679ef54c1 Mon Sep 17 00:00:00 2001 From: laughingman7743 Date: Mon, 28 Sep 2026 00:58:29 +0900 Subject: [PATCH 1/5] Limit the multiversion docs build to the newest minor versions Build master plus the latest patch release of each of the three newest minor versions instead of every released tag, and redirect URLs of versions that are no longer built to the same page on master through a root 404.html. Closes #868 Co-Authored-By: Claude Opus 5.5 --- docs/_root/404.html | 30 ++++++++++++++++++++++++++ docs/conf.py | 52 +++++++++++++++++++++++++++++++++++++++++++-- docs/testing.md | 2 +- justfile | 1 + 4 files changed, 82 insertions(+), 3 deletions(-) create mode 100644 docs/_root/404.html diff --git a/docs/_root/404.html b/docs/_root/404.html new file mode 100644 index 00000000..3b9d8648 --- /dev/null +++ b/docs/_root/404.html @@ -0,0 +1,30 @@ + + + + + + Page not found - PyAthena + + + +

Page not found

+

See the latest PyAthena documentation.

+ + diff --git a/docs/conf.py b/docs/conf.py index 23777627..cae76307 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -2,6 +2,7 @@ # # For the full list of built-in configuration values, see the documentation: # https://www.sphinx-doc.org/en/master/usage/configuration.html +import re import subprocess from datetime import datetime, timezone @@ -214,8 +215,55 @@ def setup(app): # -- Sphinx-multiversion configuration ---------------------------------------- -# Whitelist pattern for tags (semantic versioning: vX.Y.Z) -smv_tag_whitelist = r"^v\d+\.\d+\.\d+$" # Match vX.Y.Z tags +# Number of minor versions whose latest patch release is documented +SMV_MINOR_VERSIONS = 3 + + +def _select_documented_tags(count): + """Select the version tags to document. + + Picks the latest patch tag of each of the newest ``count`` minor versions, + e.g. ``v3.36.0``, ``v3.35.4`` and ``v3.34.0``. + + Args: + count: Number of minor versions to document. + + Returns: + The selected tag names, newest first. Empty when git is unavailable + or the working directory is not a git repository, as in the + per-version builds that sphinx-multiversion runs from exported trees. + """ + try: + result = subprocess.run( + ["git", "tag", "--list", "v*"], + capture_output=True, + text=True, + check=True, + ) + except (subprocess.CalledProcessError, FileNotFoundError): + return [] + + versions = [] + for tag in result.stdout.split(): + match = re.fullmatch(r"v(\d+)\.(\d+)\.(\d+)", tag) + if match: + versions.append((tuple(int(part) for part in match.groups()), tag)) + versions.sort(reverse=True) + + # Newest first, so the first tag seen for each minor version is its latest patch + latest = {} + for (major, minor, _), tag in versions: + latest.setdefault((major, minor), tag) + return list(latest.values())[:count] + + +# Whitelist pattern for tags: only the tags selected above, or none +_documented_tags = _select_documented_tags(SMV_MINOR_VERSIONS) +smv_tag_whitelist = ( + "^(" + "|".join(re.escape(tag) for tag in _documented_tags) + ")$" + if _documented_tags + else r"^$" +) # Whitelist pattern for branches smv_branch_whitelist = r"^master$" # Only build master branch diff --git a/docs/testing.md b/docs/testing.md index 96cc8b3f..0adec441 100644 --- a/docs/testing.md +++ b/docs/testing.md @@ -35,7 +35,7 @@ just docs lint just docs build ``` -`just docs build` builds documentation from the configured Git refs with sphinx-multiversion. +`just docs build` builds `master` and the latest patch release of the newest minor versions (`SMV_MINOR_VERSIONS` in `docs/conf.py`) with sphinx-multiversion. To check the working tree, including uncommitted documentation changes, also run: ```bash diff --git a/justfile b/justfile index b72f5911..6a856d04 100644 --- a/justfile +++ b/justfile @@ -75,6 +75,7 @@ _docs-help: _docs-build: uv run sphinx-multiversion docs docs/_build/html echo '' > docs/_build/html/index.html + cp docs/_root/404.html docs/_build/html/404.html echo 'pyathena.dev' > docs/_build/html/CNAME touch docs/_build/html/.nojekyll From cca5ad2e6d3a8a8940d8c52ffebdcfbdac3d44b8 Mon Sep 17 00:00:00 2001 From: laughingman7743 Date: Mon, 28 Sep 2026 01:00:10 +0900 Subject: [PATCH 2/5] Describe the 404 redirect scope precisely Co-Authored-By: Claude Opus 5.5 --- docs/_root/404.html | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/_root/404.html b/docs/_root/404.html index 3b9d8648..24c5c83c 100644 --- a/docs/_root/404.html +++ b/docs/_root/404.html @@ -12,7 +12,8 @@ Page not found - PyAthena