pyathena-dev · laughingman7743 · Sep 28, 2026 · Sep 27, 2026 · Sep 27, 2026 · Sep 27, 2026
diff --git a/docs/_root/404.html b/docs/_root/404.html
@@ -0,0 +1,31 @@
+<!--
+Copyright 2026 The PyAthena authors
+
+Licensed under the MIT License.
+See LICENSE or https://opensource.org/licenses/MIT.
+
+SPDX-License-Identifier: MIT
+-->
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8">
+    <title>Page not found - PyAthena</title>
+    <script>
+      // A missing page under a version directory, such as a version that is
+      // no longer built, redirects to the same path on master.
+      (function () {
+        var match = window.location.pathname.match(/^\/v\d+\.\d+\.\d+(\/.*)?$/);
+        if (match) {
+          window.location.replace(
+            "/master" + (match[1] || "/") + window.location.search + window.location.hash
+          );
+        }
+      })();
+    </script>
+  </head>
+  <body>
+    <h1>Page not found</h1>
+    <p>See the <a href="/master/index.html">latest PyAthena documentation</a>.</p>
+  </body>
+</html>
diff --git a/docs/_templates/versioning.html b/docs/_templates/versioning.html
@@ -7,12 +7,12 @@
 SPDX-License-Identifier: MIT
 -#}
 
-{% if versions %}
+{% if versions_newest_first %}
 <div class="sidebar-tree">
   <p class="caption" role="heading" aria-level="2"><span class="caption-text">VERSIONS:</span></p>
   <div class="version-dropdown" style="margin-bottom: 1rem;">
     <select onchange="window.location.href = this.value" style="width: 100%; padding: 0.5rem; border: 1px solid var(--color-background-border); border-radius: 0.25rem; background-color: var(--color-background-secondary); color: var(--color-foreground-primary); font-size: var(--font-size--small); cursor: pointer;">
-      {% for item in versions %}
+      {% for item in versions_newest_first %}
       <option value="{{ item.url }}" {% if item == current_version %}selected{% endif %}>
         {{ item.name }}{% if item == current_version %} (current){% endif %}
       </option>

diff --git 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
 
@@ -90,9 +91,48 @@ def config_inited(app, config):
     config.release = f"v{ver}"
 
 
+def _parse_version_tag(name):
+    """Parse a release tag name.
+
+    Args:
+        name: Git ref name, e.g. ``v3.36.0`` or ``master``.
+
+    Returns:
+        The ``(major, minor, patch)`` integers, or None if the name is not a
+        ``vX.Y.Z`` tag.
+    """
+    match = re.fullmatch(r"v(\d+)\.(\d+)\.(\d+)", name)
+    return tuple(int(part) for part in match.groups()) if match else None
+
+
+def add_versions_newest_first(app, pagename, templatename, context, doctree):
+    """Handler for html-page-context event to order the version switcher.
+
+    Adds ``versions_newest_first`` to the template context: the branches
+    (``master``) first, then the tags from the newest version to the oldest.
+    sphinx-multiversion's own ``versions`` lists tags in ref name order, which
+    puts the oldest first and would sort ``v4.10.0`` before ``v4.9.0``.
+
+    Args:
+        app: Sphinx application.
+        pagename: Name of the page being rendered.
+        templatename: Name of the page template.
+        context: Template context, updated in place.
+        doctree: Doctree of the page, or None for generated pages.
+    """
+    versions = context.get("versions")
+    if versions:
+        context["versions_newest_first"] = [
+            *versions.branches,
+            *sorted(versions.tags, key=lambda item: _parse_version_tag(item.name), reverse=True),
+        ]
+
+
 def setup(app):
     """Sphinx setup hook."""
     app.connect("config-inited", config_inited)
+    # Run after sphinx-multiversion adds ``versions`` at the default priority
+    app.connect("html-page-context", add_versions_newest_first, priority=600)
 
 
 # -- Project information -----------------------------------------------------
@@ -214,8 +254,93 @@ 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``. The latest tag of the
+    previous major version is added when those minor versions do not include
+    it and it has the Sphinx documentation, e.g. ``v3.36.1`` after ``v4.2.0``,
+    ``v4.1.0`` and ``v4.0.0``.
+
+    Args:
+        count: Number of minor versions to document.
+
+    Returns:
+        The selected tag names, newest first. Empty when git is unavailable
+        or the configuration directory is not in a git repository, as when
+        sphinx-multiversion reads each version's configuration from its
+        exported tree. Only the selection from the invoking checkout is used.
+    """
+    try:
+        result = subprocess.run(
+            ["git", "tag", "--list", "v*"],
+            capture_output=True,
+            text=True,
+            check=True,
+        )
+    except (subprocess.CalledProcessError, FileNotFoundError):
+        return []
+
+    versions = sorted(
+        (
+            (version, tag)
+            for tag in result.stdout.split()
+            if (version := _parse_version_tag(tag)) is not None
+        ),
+        reverse=True,
+    )
+    if not versions:
+        return []
+
+    # 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)
+    selected = list(latest.values())[:count]
+
+    newest_major = versions[0][0][0]
+    previous_major_latest = next(
+        (tag for (major, _, _), tag in versions if major < newest_major), None
+    )
+    if (
+        previous_major_latest
+        and previous_major_latest not in selected
+        and _has_sphinx_docs(previous_major_latest)
+    ):
+        selected.append(previous_major_latest)
+    return selected
+
+
+def _has_sphinx_docs(tag):
+    """Return whether a tag contains the Sphinx documentation.
+
+    Tags before ``v3.5.0``, including all ``v2`` tags, have no ``docs/conf.py``.
+
+    Args:
+        tag: Git tag name.
+
+    Returns:
+        True if ``docs/conf.py`` exists in the tag.
+    """
+    result = subprocess.run(
+        ["git", "cat-file", "-e", f"{tag}:docs/conf.py"],
+        capture_output=True,
+    )
+    return result.returncode == 0
+
+
+# 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
@@ -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`, the latest patch release of the newest minor versions (`SMV_MINOR_VERSIONS` in `docs/conf.py`), and the latest release of the previous major version if that tag contains `docs/conf.py`, with sphinx-multiversion.
 To check the working tree, including uncommitted documentation changes, also run:
 
 ```bash

diff --git a/justfile b/justfile
@@ -75,6 +75,7 @@ _docs-help:
 _docs-build:
     uv run sphinx-multiversion docs docs/_build/html
     echo '<meta http-equiv="refresh" content="0; url=./master/index.html">' > 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