diff --git a/.github/workflows/docs.yaml b/.github/workflows/docs.yaml index 9f5fb602..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 @@ -32,7 +33,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..46f01317 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 (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 + +# 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"