docs: use pytket-docs-theming for the docs build (#498)

* rename index file

* delete legacy docs file

* delete legacy css

* add theming submodule

* add sidebar links to index page

* update gitignore

* add scripts for installing docs deps and building the docs

* add docs README

* update docs.yml workflow

* update build and test

* fix build and test workflow

* use submodules in workflow

.github/workflows/build_and_test.yml

@@ -41,6 +41,7 @@ jobs:
     - uses: actions/checkout@v4
       with:
         fetch-depth: '0'
+        submodules: true
     - 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'
@@ -137,15 +138,18 @@ jobs:
       with:
         name: artefact-${{ matrix.os }}
         path: wheelhouse/
+    - name: Install poetry
+      run: pip install poetry
     - name: Install docs dependencies
       if:  (matrix.os == 'ubuntu-22.04') && (github.event_name == 'pull_request' || github.event_name == 'schedule' )
       run: |
-        pip install -r .github/workflows/docs/requirements.txt
+          cd docs && bash ./install.sh
+          for w in `find wheelhouse/ -type f -name "*.whl"` ; do poetry install $w ; done
     - name: Build docs
       if:  (matrix.os == 'ubuntu-22.04') && (github.event_name == 'pull_request' || github.event_name == 'schedule' )
       timeout-minutes: 20
       run: |
-        ./.github/workflows/docs/check-build-docs
+          cd docs && poetry run bash ./build-docs.sh
 
   pecos_checks:
     name: Run local-emulator tests
@@ -287,6 +291,7 @@ jobs:
     - uses: actions/checkout@v4
       with:
         fetch-depth: '0'
+        submodules: true
     - name: Set up Python 3.11
       uses: actions/setup-python@v5
       with:
@@ -297,14 +302,16 @@ jobs:
         path: wheelhouse
     - name: Install pip, wheel
       run: pip install -U pip wheel
+    - name: Install poetry
+      run: pip install poetry
     - name: Install extension
-      run: for w in `find wheelhouse/ -type f -name "*.whl"` ; do pip install $w ; done
+      run: for w in `find wheelhouse/ -type f -name "*.whl"` ; do poetry install $w ; done
     - name: Install docs dependencies
       run: |
-        pip install -r .github/workflows/docs/requirements.txt
+        cd docs
+        bash ./install.sh
     - name: Build docs
       timeout-minutes: 20
       run: |
-        cd .github/workflows/docs
-        mkdir extensions
-        ./build-docs -d ${GITHUB_WORKSPACE}/.github/workflows/docs/extensions/api
+        cd docs
+        poetry run bash ./build-docs.sh 

.github/workflows/docs.yml

@@ -7,30 +7,27 @@ on:
   schedule:
     # 04:00 every Tuesday morning
     - cron: '0 4 * * 2'
+
 jobs:
   docs:
     name: build docs
     runs-on: ubuntu-22.04
     steps:
     - uses: actions/checkout@v4
-    - name: Set up Python 3.10
+      with: 
+        submodules: true
+    - name: Set up Python 3.11
       uses: actions/setup-python@v5
       with:
-        python-version: '3.10'
-    - name: Upgrade pip and install wheel
-      run: pip install --upgrade pip wheel
-    - name: Install pytket quantinuum
-      run: pip install .
+        python-version: '3.11'
+    - name: install poetry
+      run: pip install poetry
     - name: Install docs dependencies
-      run: |
-        pip install -r .github/workflows/docs/requirements.txt
+      run: cd docs && bash install.sh 
+    - name: Install pytket-quantinuum
+      run: cd docs && poetry run pip install ../.
     - name: Test building docs
-      timeout-minutes: 20
+      timeout-minutes: 10
       run: |
-        cd .github/workflows/docs
-        mkdir extensions
-        ./build-docs -d ${GITHUB_WORKSPACE}/.github/workflows/docs/extensions
-    - uses: actions/upload-artifact@v4
-      with:
-        name: pytket-extension-docs
-        path: .github/workflows/docs/extensions/
+        cd docs
+        poetry run bash build-docs.sh

.gitignore

@@ -11,3 +11,6 @@ obj
 docs/extensions
 .ipynb_checkpoints
 pytket/extensions/quantinuum/_metadata.py
+.DS_Store
+docs/pyproject.toml
+docs/poetry.lock

.gitmodules

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

docs/README.md

@@ -0,0 +1,5 @@
+# Building the docs
+
+The docs are built by using the [pytket-docs-theming](https://github.com/CQCL/pytket-docs-theming/) repository as a git submodule. If there are issues with the docs build, feel free to open an issue or pull request there.
+
+For instructions on how to build the docs, take a look at the [extensions README](https://github.com/CQCL/pytket-docs-theming/blob/main/extensions/README.md).