docs(hugr-py): build and publish docs (#1253)

Closes #1215 Will build and publish for main branch + every tagged version with docs (currently none), using [sphinx-multiversion](https://holzhaus.github.io/sphinx-multiversion/master/index.html) With multiple versions looks like: ![image](https://github.com/CQCL/hugr/assets/12997250/f54738cf-d38f-4be7-a370-e34ab986482b) Will follow-up with a PR adding links to readme etc. once I've seen the workflow succeeds.
CQCL · Jul 3, 2024 · 902fc14 · 902fc14
1 parent 8f08b8c
commit 902fc14
Show file tree

Hide file tree

Showing 7 changed files with 112 additions and 3 deletions.
diff --git a/.github/workflows/docs.yml 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
@@ -0,0 +1,9 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <title>Redirecting to main branch</title>
+    <meta charset="utf-8">
+    <meta http-equiv="refresh" content="0; url=./main/index.html">
+    <link rel="canonical" href="https://cqcl.github.io/hugr/main/index.html">
+  </head>
+</html>
diff --git a/hugr-py/docs/api-docs/_templates/versioning.html b/hugr-py/docs/api-docs/_templates/versioning.html
@@ -0,0 +1,8 @@
+{% if versions %}
+<h3>{{ _('Versions') }}</h3>
+<ul>
+  {%- for item in versions %}
+  <li><a href="{{ item.url }}">{{ item.name }}</a></li>
+  {%- endfor %}
+</ul>
+{% endif %}
diff --git 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
@@ -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
diff --git 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"]