Migrate grid documentation to jupyter books

.github/workflows/website.yaml

@@ -1,9 +1,11 @@
-name: build_website
+name: deploy-book
 
+# Only run this when master/main/website branches change
 on:
   push:
     branches:
       - master
+      - main
       - website
 
   pull_request:
@@ -12,48 +14,57 @@ on:
       - main
       - master
 
-permissions:
-  contents: write
-  deployments: write
-  pages: write
-
+# This job installs dependencies, builds the book, and pushes it to `gh-pages`
 jobs:
-  build:
+  deploy-book:
     runs-on: ubuntu-latest
-
     permissions:
-      contents: write
-      deployments: write
       pages: write
+      # https://github.com/JamesIves/github-pages-deploy-action/issues/1110
+      contents: write
 
     steps:
-    - uses: actions/checkout@v6
-
-    - name: Install development and distributions version
-      run: |
-        pip install --upgrade pip
-        pip install ".[doc]"
-        pip install pypandoc_binary
-
-    - name: Setup pandoc
-      uses: siacodelabs/setup-pandoc@v1
-      with:
-        xelatex: true.
-
-    # didn't need to change anything here, but had to add sphinx.ext.githubpages
-    # to my conf.py extensions list. that fixes the broken uploads
-    - name: Building documentation
-      run: |
-        sphinx-apidoc -a -o ./doc/pyapi/ ./src/grid ./src/grid/tests/ ./src/grid/test/ ./src/grid/data/ --separate
-        sphinx-build -M html doc _build
-
-    # still need to build and set the PAT to get a rebuild on the pages job,
-    # apart from that quite clean and nice
-    - name: GitHub Pages Action
-      if: ${{ github.event_name == 'push' && (github.ref == 'refs/heads/main' || github.ref == 'refs/heads/master') }}
-      uses: peaceiris/actions-gh-pages@v4
-      with:
-        github_token: ${{ secrets.GITHUB_TOKEN }}
-        publish_dir: _build/html
-        publish_branch: gh-pages
-        cname: grid.qcdevs.org
+      - uses: actions/checkout@v4
+
+      # Install dependencies
+      - name: Set up Python 3.11
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install dependencies
+        run: |
+          pip install -r website/requirements.txt
+
+      # Install Grid
+      - name: Install package
+        run: |
+          pip install -e .
+
+      # Build the API docs
+      - name: Build the API documentation
+        run: |
+          rm -rf website/pyapi
+          python -m sphinx.ext.apidoc -o website/pyapi src/grid src/grid/tests/ src/grid/test/ src/grid/data/ -e -f
+
+      # Copy examples into the book so CI always builds from grid/examples
+      - name: Stage examples for website build
+        run: |
+          rm -rf website/tutorial
+          cp -r examples/ website/tutorial
+
+      # Build the book
+      - name: Build the website
+        run: |
+          jupyter-book build ./website/
+
+      # Push the book's HTML to github-pages
+      # only push to gh-pages if the master/main branch has been updated
+      - name: GitHub Pages Action
+        if: ${{ github.event_name == 'push' && (github.ref == 'refs/heads/master' || github.ref == 'refs/heads/main') }}
+        uses: peaceiris/actions-gh-pages@v4.0.0
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./website/_build/html
+          publish_branch: gh-pages
+          cname: grid.qcdevs.org