docs: fix silently failing c.i. build of the sphinx docs

.github/workflows/build_and_test.yml

@@ -31,7 +31,9 @@ jobs:
     - uses: actions/checkout@v4
       with:
         fetch-depth: '0'
-        submodules: true
+        # recursive needed as the pytket-docs-theming submodule contains
+        # the quantinuum-sphinx submodule
+        submodules: recursive
     - run: git fetch --depth=1 origin +refs/tags/*:refs/tags/* +refs/heads/*:refs/remotes/origin/*
     - name: Set up Python 3.10
       if: github.event_name == 'push' || github.event_name == 'schedule'
@@ -79,8 +81,10 @@ jobs:
     - name: Install docs dependencies
       if:  (matrix.os == 'ubuntu-latest') && (github.event_name == 'pull_request' || github.event_name == 'schedule' )
       run: |
-        cd docs && bash ./install.sh
-        for w in `find wheelhouse/ -type f -name "*.whl"` ; do poetry run pip install $w ; done
+        bash ./docs/install.sh
+        cd docs
+        for w in `find ../wheelhouse/ -type f -name "*.whl"` ; do poetry run pip install $w ; done
+        cd ..
     - name: Build docs
       if:  (matrix.os == 'ubuntu-latest') && (github.event_name == 'pull_request' || github.event_name == 'schedule' )
       timeout-minutes: 20

docs/build-docs.sh

@@ -1,20 +1,32 @@
 #!/bin/bash
+set -e
 rm -rf build/
 
+# This build script is only used for local docs build.
+# The docs build for the website uses a different script.
+
 # Move theming elements into the docs folder
-cp -R pytket-docs-theming/_static .
 cp -R pytket-docs-theming/quantinuum-sphinx .
 cp pytket-docs-theming/conf.py .
+cp -R pytket-docs-theming/_static . # Currently unused
 
 # Get the name of the project
-EXTENSION_NAME="$(basename "$(dirname `pwd`)")"
+PACKAGE="$(basename "$(dirname `pwd`)")"
+
+# Get pytket extension version
+VERSION="$(pip show $PACKAGE | grep Version | awk '{print $2}')"
 
-# Correct github link in navbar
-sed -i '' 's#CQCL/tket#CQCL/'$EXTENSION_NAME'#' _static/nav-config.js
+# Output package version
+echo extension version $VERSION
 
-# Build the docs. Ensure we have the correct project title.
-sphinx-build -b html -D html_title="$EXTENSION_NAME" . build 
+# Combine to set title
+PACKAGE+=" $VERSION"
 
+# Build the docs setting the html_title
+sphinx-build -b html . build -D html_title="$PACKAGE API documentation" -W
+
+# Find and replace all generated links that use _tket in the built html.
+# Note that MACOS and linux have differing sed syntax.
 if [[ "$OSTYPE" == "darwin"* ]]; then
     find build/ -type f -name "*.html" | xargs sed -e 's/pytket._tket/pytket/g' -i ""
     sed -i '' 's/pytket._tket/pytket/g' build/searchindex.js
@@ -23,7 +35,8 @@ else
     sed -i 's/pytket._tket/pytket/g' build/searchindex.js
 fi
 
-# Remove copied files. This ensures reusability.
-rm -r _static 
+# Remove copied files after build is done. This ensures reusability.
 rm -r quantinuum-sphinx
-rm conf.py
+rm conf.py
+
+set +e

docs/install.sh

@@ -1,8 +1,12 @@
+set -e
+
+
 # Copy over poetry dependencies from theming repository
-cp pytket-docs-theming/extensions/pyproject.toml .
-cp pytket-docs-theming/extensions/poetry.lock .
+cp docs/pytket-docs-theming/extensions/pyproject.toml .
+cp docs/pytket-docs-theming/extensions/poetry.lock .
 
 # Install the docs dependencies. Creates a .venv directory in docs
 poetry install
 
-# NOTE: Editable wheel should be installed separately.
+# NOTE: Editable wheel should be installed separately.
+set +e