diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
new file mode 100644
index 000000000..2f22b7579
--- /dev/null
+++ b/.github/workflows/docs.yml
@@ -0,0 +1,63 @@
+name: Build and publish docs
+
+on:
+ workflow_dispatch:
+ push:
+ branches:
+ - main
+ # only run if there are changes in the hugr-py directory
+ paths:
+ - 'hugr-py/**'
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+ contents: read
+ pages: write
+ id-token: write
+
+# Allow only one concurrent deployment, skipping runs queued between the run
+# in-progress and latest queued.
+concurrency:
+ group: "pages"
+ cancel-in-progress: true
+
+jobs:
+ build:
+ name: Build docs.
+ runs-on: ubuntu-latest
+ defaults:
+ run:
+ working-directory: ./hugr-py
+ steps:
+ - uses: actions/checkout@v4
+ - name: Install poetry
+ run: pipx install poetry
+ - name: Set up Python '3.10'
+ uses: actions/setup-python@v5
+ with:
+ python-version: '3.10'
+ cache: "poetry"
+ - name: Install HUGR
+ run: poetry install --with docs
+ - name: Build docs
+ run: |
+ cd docs
+ ./build.sh
+ - name: Upload artifact.
+ uses: actions/upload-pages-artifact@v3
+ with:
+ path: ./hugr-py/docs/build
+
+ publish:
+ name: Publish docs.
+ environment:
+ name: github-pages
+ url: ${{ steps.deployment.outputs.page_url }}
+ runs-on: ubuntu-latest
+ needs: build
+ steps:
+ - name: Setup Pages
+ uses: actions/configure-pages@v5
+ - name: Deploy to GitHub Pages.
+ id: deployment
+ uses: actions/deploy-pages@v4
diff --git a/hugr-py/docs/_static/_redirect.html b/hugr-py/docs/_static/_redirect.html
new file mode 100644
index 000000000..3f20c9c91
--- /dev/null
+++ b/hugr-py/docs/_static/_redirect.html
@@ -0,0 +1,9 @@
+
+
+
+ Redirecting to main branch
+
+
+
+
+
diff --git a/hugr-py/docs/api-docs/_templates/versioning.html b/hugr-py/docs/api-docs/_templates/versioning.html
new file mode 100644
index 000000000..7c5ab1474
--- /dev/null
+++ b/hugr-py/docs/api-docs/_templates/versioning.html
@@ -0,0 +1,8 @@
+{% if versions %}
+{{ _('Versions') }}
+
+{% endif %}
diff --git a/hugr-py/docs/api-docs/conf.py b/hugr-py/docs/api-docs/conf.py
index 98ecdd0db..ceace6b8d 100644
--- a/hugr-py/docs/api-docs/conf.py
+++ b/hugr-py/docs/api-docs/conf.py
@@ -13,6 +13,7 @@
"sphinx.ext.autosummary",
"sphinx.ext.viewcode",
"sphinx.ext.intersphinx",
+ "sphinx_multiversion",
]
html_theme = "sphinx_book_theme"
@@ -36,6 +37,18 @@
templates_path = ["_templates"]
exclude_patterns = ["_build", "Thumbs.db", ".DS_Store", "conftest.py"]
+html_sidebars = {
+ "**": [
+ "navbar-logo.html",
+ "icon-links.html",
+ "search-button-field.html",
+ "sbt-sidebar-nav.html",
+ "versioning.html",
+ ],
+}
+
+smv_branch_whitelist = "main"
+smv_tag_whitelist = r"^hugr-py-.*$"
intersphinx_mapping = {
"python": ("https://docs.python.org/3/", None),
diff --git a/hugr-py/docs/build.sh b/hugr-py/docs/build.sh
index 57eef23b6..d4e51e3bb 100755
--- a/hugr-py/docs/build.sh
+++ b/hugr-py/docs/build.sh
@@ -3,5 +3,6 @@
mkdir build
touch build/.nojekyll # Disable jekyll to keep files starting with underscores
-
-sphinx-build -b html ./api-docs ./build/api-docs
+# copy redirect file
+cp ./_static/_redirect.html ./build/index.html
+sphinx-multiversion ./api-docs ./build
diff --git a/hugr-py/poetry.lock b/hugr-py/poetry.lock
index 2006a16d2..555981053 100644
--- a/hugr-py/poetry.lock
+++ b/hugr-py/poetry.lock
@@ -576,6 +576,20 @@ code-style = ["pre-commit"]
doc = ["ablog", "folium", "ipywidgets", "matplotlib", "myst-nb", "nbclient", "numpy", "numpydoc", "pandas", "plotly", "sphinx-copybutton", "sphinx-design", "sphinx-examples", "sphinx-tabs", "sphinx-thebe", "sphinx-togglebutton", "sphinxcontrib-bibtex", "sphinxcontrib-youtube", "sphinxext-opengraph"]
test = ["beautifulsoup4", "coverage", "defusedxml", "myst-nb", "pytest", "pytest-cov", "pytest-regressions", "sphinx_thebe"]
+[[package]]
+name = "sphinx-multiversion"
+version = "0.2.4"
+description = "Add support for multiple versions to sphinx"
+optional = false
+python-versions = "*"
+files = [
+ {file = "sphinx-multiversion-0.2.4.tar.gz", hash = "sha256:5cd1ca9ecb5eed63cb8d6ce5e9c438ca13af4fa98e7eb6f376be541dd4990bcb"},
+ {file = "sphinx_multiversion-0.2.4-py3-none-any.whl", hash = "sha256:dec29f2a5890ad68157a790112edc0eb63140e70f9df0a363743c6258fbeb478"},
+]
+
+[package.dependencies]
+sphinx = ">=2.1"
+
[[package]]
name = "sphinxcontrib-applehelp"
version = "1.0.8"
@@ -712,4 +726,4 @@ zstd = ["zstandard (>=0.18.0)"]
[metadata]
lock-version = "2.0"
python-versions = ">=3.10"
-content-hash = "0e927e63660da3f23f2e241a006c7255a780303326e967baec4f0436f16bbd84"
+content-hash = "c0e0f4ebdc6d0b9e2b6e71841109ee1a47f42d850aa5621c5723006a9dd9d99a"
diff --git a/hugr-py/pyproject.toml b/hugr-py/pyproject.toml
index 739ced174..a86abf544 100644
--- a/hugr-py/pyproject.toml
+++ b/hugr-py/pyproject.toml
@@ -33,6 +33,7 @@ optional = true
[tool.poetry.group.docs.dependencies]
sphinx = "^7.2.6"
sphinx-book-theme = "^1.1.2"
+sphinx-multiversion = "^0.2.4"
[build-system]
requires = ["poetry-core"]