Infra: Combine manual and examples build (#339)

* use poetry for dependency management

* add additonal manual dependencies

* delete legacy example

* update manual script

* use pydata theme and clean index page

* remove legacy python -> jupyter conversion

* update manual workflow

* move manual and examples into docs directory

* update build script

* build-manual -> build-docs

* update .gitignore

* delete jupyterbook files

* add openfermion nbsphinx and ipyparallel

* add static files

* move static folder

* delete duplicate static files

* change manual title

* use Myst-NB instead of NBSphinx

* clear out old files and update configuration

* regenerate lock file

* update .giignore and build-docs script

* rename build script

* fix duplicate jupyter execution bug

* fix some headings

* ingore cached files

* collapse secondary sidebars

* use quantinuum theming

* add furo dependency

* New index page structure

* fix maths rendering problems

* remove jupyterbook build workflow

* rename build workflow

* simplify poetry dependencies and regenerate lock file

* try --no-update flag

* fix typo in workflow

* remove outdated quantinuum-shinx dependency

* remove legacy contributing file

* use poetry run instead of poetry shell

* remove unused sphinx extension

* install graphviz in docs build

* delete unused _static files

* remove --no-update flag

* add favicon

* add myst_nb extension again to fix notebook build

* fail sphinx build on warnings

* fix problems with qujax example headings

* add getting started guide to index page

* correctly exclude notebooks non-executable notebooks from build

* fix another duplicate execution bug

* new file sturcture for example notebook categories

* fail build on warnings

* update navbar items for user guide

* remove unused extensions

* delete old workflow for testing notebooks

* add download option to notebooks

* allow execution of classification example

* change name of workflow

* try updating gitmodules file

* fix headings in  classification example

* Fix submodule.

* use submodules in build

* update submodule to latest

* update to latest quantinuum-sphinx

* add 404.html file back in

* add more intersphinx mappings for extensions

* update pytket-cirq ref

* remove all content for archived pytket-qsharp

* add some html to redirect from old pages

* add index.html file back into docs

* remove qsharp stuff

* don't excute flaky qujax example

* don't execute qujax qaoa

* use latest pytket v1.31.0

* set package mode to false

* don't execute big vqe notebook

* delete dummy directories with redirects

---------

Co-authored-by: aidanCQ <aidan.keay@quantinuum.com>

.github/workflows/check-manual.yml → .github/workflows/check-docs-build.yml

@@ -1,4 +1,4 @@
-name: check manual
+name: check docs build
 
 on:
   pull_request:
@@ -28,35 +28,28 @@ jobs:
             - '.github/**'
 
   check:
-    name: check manual
+    name: check docs build
     needs: changes
     if: github.event_name == 'schedule' || needs.changes.outputs.manual == 'true'
     runs-on: ubuntu-22.04
     steps:
     - uses: actions/checkout@v4
       with:
+        submodules: true
         fetch-depth: '0'
     - run: git fetch --depth=1 origin +refs/tags/*:refs/tags/* +refs/heads/*:refs/remotes/origin/*
     - name: Set up Python 3.11
       uses: actions/setup-python@v5
       with:
         python-version: 3.11
-    - name: install python requirements for manual
+    - name: install python requirements for docs
       run: |
-        python -m pip install --upgrade pip
-        python -m pip install wheel
-        python -m pip install -c manual_constraints.txt sphinx sphinx-book-theme jupyter-sphinx quimb
-        python -m pip install -r manual_requirements.txt
-        python -m pip install kahypar
-        python -m pip install sphinx-copybutton
-        python -m pip install ipyparallel
-        python -m pip install qiskit-algorithms
+        python -m pip install poetry
+        poetry install
     - name: install graphviz
       run: |
-        sudo apt-get update
-        sudo apt-get install graphviz
-    - name: build manual
+          sudo apt-get update
+          sudo apt-get install graphviz
+    - name: build manual and examples
       run: |
-        cd manual/
-        sed "s/REQUIREMENTS/$(sed -e 's/[\&/]/\\&/g' -e 's/$/\\n/' ../manual_requirements.txt | tr -d '\n')/" index-rst-template > index.rst
-        sphinx-build -b html . build -W
+        poetry run ./build-docs.sh

.gitignore

@@ -4,7 +4,14 @@ dist
 .vscode
 .venv
 .mypy_cache
-manual/build
-manual/jupyter_execute
+docs/manual/build
+docs/manual/jupyter_execute
 examples/_build/
-*.ipynb_checkpoints
+docs/manual/jupyter_execute
+docs/examples/_build/
+*.ipynb_checkpoints
+docs/build/jupyter_execute/
+docs/build/examples/_build/
+docs/build/
+docs/jupyter_execute
+docs/.jupyter_cache

.gitmodules

@@ -0,0 +1,4 @@
+[submodule "docs/quantinuum-sphinx"]
+	path = docs/quantinuum-sphinx
+	url = https://github.com/CQCL/quantinuum-sphinx.git
+	branch = dist

build-docs.sh

@@ -0,0 +1,7 @@
+#!/bin/sh
+
+cd docs/
+
+rm -rf build/
+sphinx-build -b html . build -W
+

docs/404.html

@@ -1,17 +1,20 @@
 <!DOCTYPE html>
 <html>
-  <head>
-    <meta charset="utf-8"/>
-    <meta http-equiv="refresh" content="0; url=https://tket.quantinuum.com/user-manual/"/>
+
+<head>
+    <meta charset="utf-8" />
+    <meta http-equiv="refresh" content="0; url=https://tket.quantinuum.com/user-manual/" />
     <script type="text/javascript">
-      window.location.href = "https://tket.quantinuum.com/user-manual/"
+        window.location.href = "https://tket.quantinuum.com/user-manual/"
     </script>
     <title>TKET docs have moved to tket.quantinuum.com</title>
-  </head>
-  <body>
+</head>
+
+<body>
     <p>
-      If you are not redirected automatically, follow
-      <a href="https://tket.quantinuum.com/user-manual/">this link to the user manual on tket.quantinuum.com</a>.
+        If you are not redirected automatically, follow
+        <a href="https://tket.quantinuum.com/user-manual/">this link to the user manual on tket.quantinuum.com</a>.
     </p>
-  </body>
-</html>
+</body>
+
+</html>

docs/_static/nav-config.js

@@ -0,0 +1,41 @@
+const navConfig = {
+
+    "navTextLinks": [
+        {
+            "title": "API Docs",
+            "href": "../api-docs",
+            "pathMatch": "somewhere",
+        },
+        {
+            "title": "Blog",
+            "href": "../blog/",
+            "pathMatch": "somewhere",
+        },
+        {
+            "title": "User Guide",
+            "href": "../user-guide",
+            "pathMatch": "somewhere",
+        },
+    ],
+    "navProductName": "TKET",
+    "navIconLinks": [
+        {
+            "title": "TKET Github",
+            "href": "https://github.com/CQCL/tket",
+            "pathMatch": "somewhere",
+            "iconImageURL": "_static/assets/github.svg",
+        },
+        {
+            "title": "TKET Slack Channel",
+            "href": "https://tketusers.slack.com/",
+            "pathMatch": "somewhere",
+            "iconImageURL": "_static/assets/slack.svg",
+        },
+        {
+            "title": "TKET Stack Exchange",
+            "href": "https://quantumcomputing.stackexchange.com/questions/tagged/pytket",
+            "pathMatch": "somewhere",
+            "iconImageURL": "_static/assets/stack.svg",
+        },
+    ],
+}

docs/conf.py

@@ -0,0 +1,60 @@
+# -*- coding: utf-8 -*-
+
+# Configuration file for the Sphinx documentation builder.
+# See https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+copyright = "2020-2024, Quantinuum"
+author = "Quantinuum"
+
+
+html_title = "pytket user guide"
+
+extensions = [
+    "sphinx.ext.intersphinx",
+    "sphinx.ext.mathjax",
+    "jupyter_sphinx",
+    "sphinx_copybutton",
+    "sphinx.ext.autosectionlabel",
+    "myst_nb",
+]
+
+myst_enable_extensions = ["dollarmath", "html_image", "attrs_inline"]
+
+html_theme = "furo"
+templates_path = ["./quantinuum-sphinx/_templates/"]
+html_static_path = ["./quantinuum-sphinx/_static/", "_static/"]
+
+pytketdoc_base = "https://tket.quantinuum.com/api-docs/"
+
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/3/", None),
+    "pytket": (pytketdoc_base, None),
+    "qiskit": ("https://docs.quantum.ibm.com/api/qiskit", None),
+    "pytket-qiskit": ("https://tket.quantinuum.com/extensions/pytket-qiskit/", None),
+    "pytket-quantinuum": (
+        "https://tket.quantinuum.com/extensions/pytket-quantinuum/",
+        None,
+    ),
+    "pytket-qujax": ("https://tket.quantinuum.com/extensions/pytket-qujax/", None),
+    "pytket-cirq": ("https://tket.quantinuum.com/extensions/pytket-cirq/", None),
+    "sympy": ("https://docs.sympy.org/latest/", None),
+}
+
+
+nb_execution_mode = "cache"
+
+nb_execution_excludepatterns = [
+    "examples/backends/Forest_portability_example.ipynb",
+    "examples/backends/backends_example.ipynb",
+    "examples/backends/qiskit_integration.ipynb",
+    "examples/backends/comparing_simulators.ipynb",
+    "examples/algorithms_and_protocols/expectation_value_example.ipynb",
+    "examples/algorithms_and_protocols/pytket-qujax_heisenberg_vqe.ipynb",
+    "examples/algorithms_and_protocols/pytket-qujax-classification.ipynb",
+    "examples/algorithms_and_protocols/pytket-qujax_qaoa.ipynb",
+    "examples/algorithms_and_protocols/ucc_vqe.ipynb",
+    "examples/algorithms_and_protocols/spam_example.ipynb",
+    "examples/algorithms_and_protocols/entanglement_swapping.ipynb",
+]
+
+exclude_patterns = ["jupyter_execute/*", ".jupyter_cache", "manual/README.md"]