From 215ba7e7e7266780d021de3a0a8710a7f8016382 Mon Sep 17 00:00:00 2001 From: laughingman7743 Date: Sat, 18 Oct 2025 15:00:42 +0900 Subject: [PATCH 1/3] docs: Implement version selector with sphinx-multiversion MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This PR implements a version selector for the documentation using sphinx-multiversion. Users can now easily switch between different versions of the documentation. Changes: - Add sphinx-multiversion dependency to pyproject.toml - Configure sphinx-multiversion to build v3.x.x tags and master branch - Add dropdown-style version selector in sidebar (after CONTENTS) - Update GitHub Actions workflow to use 'make docs' command - Update Makefile to use sphinx-multiversion for docs target - Remove unused docs/Makefile and docs/make.bat files - Configure Furo theme options for source repository links The version selector is displayed as a dropdown below CONTENTS in the sidebar, matching the style of CONTENTS: heading. The root URL redirects to master branch documentation. Closes #612 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- .github/workflows/docs.yaml | 1 - Makefile | 5 ++++- docs/Makefile | 20 ------------------- docs/_templates/versioning.html | 14 +++++++++++++ docs/conf.py | 32 +++++++++++++++++++++++++++++- docs/make.bat | 35 --------------------------------- pyproject.toml | 1 + uv.lock | 15 ++++++++++++++ 8 files changed, 65 insertions(+), 58 deletions(-) delete mode 100644 docs/Makefile create mode 100644 docs/_templates/versioning.html delete mode 100644 docs/make.bat diff --git a/.github/workflows/docs.yaml b/.github/workflows/docs.yaml index 9f5fb602..4501b423 100644 --- a/.github/workflows/docs.yaml +++ b/.github/workflows/docs.yaml @@ -32,7 +32,6 @@ jobs: enable-cache: true - run: | uv sync --group dev - uv build make docs - name: Upload artifact uses: actions/upload-pages-artifact@v3 diff --git a/Makefile b/Makefile index f85046c4..44c76743 100644 --- a/Makefile +++ b/Makefile @@ -27,7 +27,10 @@ tox: .PHONY: docs docs: - cd ./docs && uv run $(MAKE) clean html + uv build + uv run sphinx-multiversion docs docs/_build/html + echo '' > docs/_build/html/index.html + touch docs/_build/html/.nojekyll .PHONY: tool tool: diff --git a/docs/Makefile b/docs/Makefile deleted file mode 100644 index d4bb2cbb..00000000 --- a/docs/Makefile +++ /dev/null @@ -1,20 +0,0 @@ -# Minimal makefile for Sphinx documentation -# - -# You can set these variables from the command line, and also -# from the environment for the first two. -SPHINXOPTS ?= -SPHINXBUILD ?= sphinx-build -SOURCEDIR = . -BUILDDIR = _build - -# Put it first so that "make" without argument is like "make help". -help: - @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) - -.PHONY: help Makefile - -# Catch-all target: route all unknown targets to Sphinx using the new -# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). -%: Makefile - @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/docs/_templates/versioning.html b/docs/_templates/versioning.html new file mode 100644 index 00000000..c9f7ef6d --- /dev/null +++ b/docs/_templates/versioning.html @@ -0,0 +1,14 @@ +{% if versions %} +
+

VERSIONS:

+
+ +
+
+{% endif %} diff --git a/docs/conf.py b/docs/conf.py index 8687507e..90e6929d 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -34,11 +34,12 @@ def get_version(): extensions = [ "sphinx.ext.autodoc", - "sphinx.ext.autosummary", + "sphinx.ext.autosummary", "sphinx.ext.viewcode", "sphinx.ext.napoleon", "sphinx.ext.intersphinx", "sphinx.ext.githubpages", + "sphinx_multiversion", ] # Napoleon settings for Google-style docstrings @@ -96,3 +97,32 @@ def get_version(): "source_branch": "master", "source_directory": "docs/", } + +# Sidebar templates +html_sidebars = { + "**": [ + "sidebar/brand.html", + "sidebar/search.html", + "sidebar/scroll-start.html", + "sidebar/navigation.html", + "versioning.html", + "sidebar/scroll-end.html", + ] +} + +# -- Sphinx-multiversion configuration ---------------------------------------- + +# Whitelist pattern for tags +smv_tag_whitelist = r"^v3\.\d+\.\d+$" # Match v3.x.x tags only + +# Whitelist pattern for branches +smv_branch_whitelist = r"^master$" # Only build master branch + +# Whitelist pattern for remotes +smv_remote_whitelist = r"^origin$" # Only build from origin remote + +# Output all versions to the root directory +smv_outputdir_format = "{ref.name}" + +# Specify the latest version (used for stable redirect) +smv_latest_version = "master" diff --git a/docs/make.bat b/docs/make.bat deleted file mode 100644 index 32bb2452..00000000 --- a/docs/make.bat +++ /dev/null @@ -1,35 +0,0 @@ -@ECHO OFF - -pushd %~dp0 - -REM Command file for Sphinx documentation - -if "%SPHINXBUILD%" == "" ( - set SPHINXBUILD=sphinx-build -) -set SOURCEDIR=. -set BUILDDIR=_build - -%SPHINXBUILD% >NUL 2>NUL -if errorlevel 9009 ( - echo. - echo.The 'sphinx-build' command was not found. Make sure you have Sphinx - echo.installed, then set the SPHINXBUILD environment variable to point - echo.to the full path of the 'sphinx-build' executable. Alternatively you - echo.may add the Sphinx directory to PATH. - echo. - echo.If you don't have Sphinx installed, grab it from - echo.https://www.sphinx-doc.org/ - exit /b 1 -) - -if "%1" == "" goto help - -%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% -goto end - -:help -%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% - -:end -popd diff --git a/pyproject.toml b/pyproject.toml index f1a84ac2..7588e79f 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -59,6 +59,7 @@ dev = [ "pytest-xdist", "pytest-dependency", "sphinx", + "sphinx-multiversion", "furo", "types-python-dateutil", ] diff --git a/uv.lock b/uv.lock index 789f7fa3..7ea25027 100644 --- a/uv.lock +++ b/uv.lock @@ -884,6 +884,7 @@ dev = [ { name = "pytest-dependency" }, { name = "pytest-xdist" }, { name = "sphinx" }, + { name = "sphinx-multiversion" }, { name = "sqlalchemy" }, { name = "types-python-dateutil" }, ] @@ -915,6 +916,7 @@ dev = [ { name = "pytest-dependency" }, { name = "pytest-xdist" }, { name = "sphinx" }, + { name = "sphinx-multiversion" }, { name = "sqlalchemy", specifier = ">=1.0.0" }, { name = "types-python-dateutil" }, ] @@ -1106,6 +1108,19 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/3c/dd/018ce05c532a22007ac58d4f45232514cd9d6dd0ee1dc374e309db830983/sphinx_basic_ng-1.0.0b2-py3-none-any.whl", hash = "sha256:eb09aedbabfb650607e9b4b68c9d240b90b1e1be221d6ad71d61c52e29f7932b", size = 22496 }, ] +[[package]] +name = "sphinx-multiversion" +version = "0.2.4" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "sphinx" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/9a/10/25231164a97a9016bdc73a3530af8f4a6846bdc564af1460af2ff3e59a50/sphinx-multiversion-0.2.4.tar.gz", hash = "sha256:5cd1ca9ecb5eed63cb8d6ce5e9c438ca13af4fa98e7eb6f376be541dd4990bcb", size = 7024 } +wheels = [ + { url = "https://files.pythonhosted.org/packages/19/51/203bb30b3ce76373237288e92cb71fb66f80ee380473f36bfe8a9d299c5d/sphinx_multiversion-0.2.4-py2.py3-none-any.whl", hash = "sha256:5c38d5ce785a335d8c8d768b46509bd66bfb9c6252b93b700ca8c05317f207d6", size = 9597 }, + { url = "https://files.pythonhosted.org/packages/05/ad/4989e6be165805694e93d09bc57425aa1368273b7de4fe3083fe4310803a/sphinx_multiversion-0.2.4-py3-none-any.whl", hash = "sha256:dec29f2a5890ad68157a790112edc0eb63140e70f9df0a363743c6258fbeb478", size = 9642 }, +] + [[package]] name = "sphinxcontrib-applehelp" version = "2.0.0" From bd32ff417669390753a7219371e7760a9caf1a04 Mon Sep 17 00:00:00 2001 From: laughingman7743 Date: Sat, 18 Oct 2025 15:13:54 +0900 Subject: [PATCH 2/3] docs: Support all semantic versioning tags (not just v3.x.x) Change tag whitelist pattern from v3.x.x to vX.Y.Z to support future major versions (v4, v5, etc.) without configuration changes. --- docs/conf.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index 90e6929d..46f01317 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -112,8 +112,8 @@ def get_version(): # -- Sphinx-multiversion configuration ---------------------------------------- -# Whitelist pattern for tags -smv_tag_whitelist = r"^v3\.\d+\.\d+$" # Match v3.x.x tags only +# Whitelist pattern for tags (semantic versioning: vX.Y.Z) +smv_tag_whitelist = r"^v\d+\.\d+\.\d+$" # Match vX.Y.Z tags # Whitelist pattern for branches smv_branch_whitelist = r"^master$" # Only build master branch From c09dbfe811e87cc2663a01d93eae902a8936ac06 Mon Sep 17 00:00:00 2001 From: laughingman7743 Date: Sat, 18 Oct 2025 15:23:29 +0900 Subject: [PATCH 3/3] docs: Trigger documentation build on tag push Add tag push trigger (v*) to documentation workflow so that new version documentation is built and deployed automatically when a new version is released. --- .github/workflows/docs.yaml | 1 + 1 file changed, 1 insertion(+) diff --git a/.github/workflows/docs.yaml b/.github/workflows/docs.yaml index 4501b423..7690dc14 100644 --- a/.github/workflows/docs.yaml +++ b/.github/workflows/docs.yaml @@ -4,6 +4,7 @@ on: workflow_dispatch: push: branches: ['master'] + tags: ['v*'] permissions: contents: read