fix: Fix version detection in sphinx-multiversion documentation builds

Makefile

@@ -27,7 +27,6 @@ tox:
 
 .PHONY: docs
 docs:
-	uv 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
 	touch docs/_build/html/.nojekyll

docs/conf.py

@@ -2,22 +2,87 @@
 #
 # For the full list of built-in configuration values, see the documentation:
 # https://www.sphinx-doc.org/en/master/usage/configuration.html
+import subprocess
 from datetime import datetime, timezone
-from pathlib import Path
 
 
 def get_version():
+    # Use git commands to get version from the checked-out ref.
+    # sphinx-multiversion checks out each ref to a temp directory and runs Sphinx there.
+    # Use current working directory to get the version of the checked-out ref.
+    try:
+        # Try to get exact tag (for tagged commits)
+        result = subprocess.run(
+            ["git", "describe", "--tags", "--exact-match"],
+            capture_output=True,
+            text=True,
+            check=True,
+        )
+        tag = result.stdout.strip()
+        if tag and tag.startswith("v"):
+            return tag[1:]  # Remove 'v' prefix
+        return tag
+    except (subprocess.CalledProcessError, FileNotFoundError):
+        pass
+
+    # Try to get version using git describe (for non-tagged commits)
+    try:
+        result = subprocess.run(
+            ["git", "describe", "--tags", "--always"],
+            capture_output=True,
+            text=True,
+            check=True,
+        )
+        version_str = result.stdout.strip()
+        if version_str and version_str.startswith("v"):
+            return version_str[1:]  # Remove 'v' prefix
+        return version_str
+    except (subprocess.CalledProcessError, FileNotFoundError):
+        pass
+
+    # Fallback to _version.py (for local development builds)
     try:
-        # Try to import from _version.py (generated by setuptools-scm)
         from pyathena._version import __version__
+
         return __version__
     except ImportError:
-        try:
-            # Fallback to importlib.metadata
-            from importlib.metadata import version
-            return version("PyAthena")
-        except Exception:
-            return "unknown"
+        pass
+
+    # Final fallback to importlib.metadata
+    try:
+        from importlib.metadata import version
+
+        return version("PyAthena")
+    except Exception:
+        return "unknown"
+
+
+# -- Setup function ----------------------------------------------------------
+
+
+def config_inited(app, config):
+    """Handler for config-inited event to set version dynamically."""
+    smv_current_version = getattr(config, "smv_current_version", None)
+
+    if smv_current_version:
+        # sphinx-multiversion sets this to the ref name (e.g., "v3.19.0" or "master")
+        if smv_current_version.startswith("v") and smv_current_version[1:2].isdigit():
+            # It's a version tag like "v3.19.0"
+            ver = smv_current_version[1:]  # Remove 'v' prefix
+        else:
+            # It's a branch name like "master", use git to get version
+            ver = get_version()
+    else:
+        # Not running under sphinx-multiversion, use git
+        ver = get_version()
+
+    config.version = f"v{ver}"
+    config.release = f"v{ver}"
+
+
+def setup(app):
+    """Sphinx setup hook."""
+    app.connect("config-inited", config_inited)
 
 
 # -- Project information -----------------------------------------------------
@@ -26,8 +91,9 @@ def get_version():
 project = "PyAthena"
 copyright = f"{datetime.now(timezone.utc).year}, laughingman7743"
 author = "laughingman7743"
-version = f"v{get_version()}"
-release = f"v{get_version()}"
+# Version will be set dynamically in setup() function
+version = ""
+release = ""
 
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
@@ -60,11 +126,11 @@ def get_version():
 
 # Autodoc settings
 autodoc_default_options = {
-    'members': True,
-    'member-order': 'bysource',
-    'special-members': '__init__',
-    'undoc-members': True,
-    'exclude-members': '__weakref__'
+    "members": True,
+    "member-order": "bysource",
+    "special-members": "__init__",
+    "undoc-members": True,
+    "exclude-members": "__weakref__",
 }
 
 # Autosummary settings
@@ -73,9 +139,9 @@ def get_version():
 
 # Intersphinx mapping
 intersphinx_mapping = {
-    'python': ('https://docs.python.org/3', None),
-    'pandas': ('https://pandas.pydata.org/pandas-docs/stable', None),
-    'pyarrow': ('https://arrow.apache.org/docs/', None),
+    "python": ("https://docs.python.org/3", None),
+    "pandas": ("https://pandas.pydata.org/pandas-docs/stable", None),
+    "pyarrow": ("https://arrow.apache.org/docs/", None),
 }
 
 templates_path = ["_templates"]

pyproject.toml

@@ -106,7 +106,6 @@ line-length = 100
 exclude = [
     ".venv",
     ".tox",
-    "docs",
 ]
 target-version = "py39"