From 88c7eb9a3d1bdde829c7e68790e1a08b7bcbc3c1 Mon Sep 17 00:00:00 2001 From: laughingman7743 Date: Sat, 18 Oct 2025 18:06:32 +0900 Subject: [PATCH 1/2] fix: Fix version detection in sphinx-multiversion documentation builds MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This commit fixes the issue where documentation versions were displayed incorrectly in the built HTML files. ## Problem When sphinx-multiversion builds documentation for different tags and branches, the version string was not correctly detected: - v3.18.0 showed "vNone" - v3.19.0 showed dev version instead of "v3.19.0" - v3.5.0 showed "v3.4.0" instead of "v3.5.0" ## Solution Added a `config-inited` event handler that uses sphinx-multiversion's `smv_current_version` config value to set the correct version: - For version tags (like "v3.19.0"), extract the version directly from the tag name - For branches (like "master"), fall back to git commands to get dev version - Removed `uv build` from Makefile since version is now set dynamically ## Testing Local build with `make docs` now correctly shows: - v3.18.0 → "v3.18.0" ✓ - v3.19.0 → "v3.19.0" ✓ - v3.5.0 → "v3.5.0" ✓ - master → correct dev version ✓ 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- Makefile | 1 - docs/conf.py | 82 +++++++++++++++++++++++++++++++++++++++++++++------- 2 files changed, 72 insertions(+), 11 deletions(-) diff --git a/Makefile b/Makefile index 44c76743..3c0289b8 100644 --- a/Makefile +++ b/Makefile @@ -27,7 +27,6 @@ tox: .PHONY: docs docs: - uv build uv run sphinx-multiversion docs docs/_build/html echo '' > docs/_build/html/index.html touch docs/_build/html/.nojekyll diff --git a/docs/conf.py b/docs/conf.py index 46f01317..1b25de4f 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -2,23 +2,84 @@ # # 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 ----------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information @@ -26,8 +87,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 From 453c719edc6a00b53055beccf3becbe167ddce10 Mon Sep 17 00:00:00 2001 From: laughingman7743 Date: Sat, 18 Oct 2025 18:08:20 +0900 Subject: [PATCH 2/2] chore: Enable ruff formatting for docs directory MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Remove 'docs' from ruff exclude list in pyproject.toml - Apply ruff formatting to docs/conf.py 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- docs/conf.py | 20 ++++++++++++-------- pyproject.toml | 1 - 2 files changed, 12 insertions(+), 9 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index 1b25de4f..15a8cf37 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -56,8 +56,10 @@ def get_version(): 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) @@ -77,10 +79,12 @@ def config_inited(app, config): config.version = f"v{ver}" config.release = f"v{ver}" + def setup(app): """Sphinx setup hook.""" app.connect("config-inited", config_inited) + # -- Project information ----------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information @@ -122,11 +126,11 @@ def setup(app): # 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 @@ -135,9 +139,9 @@ def setup(app): # 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"] diff --git a/pyproject.toml b/pyproject.toml index 7588e79f..7855f907 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -106,7 +106,6 @@ line-length = 100 exclude = [ ".venv", ".tox", - "docs", ] target-version = "py39"