Render and display tutorials (#3)

Co-authored-by: Rhodri Davies <rhodri.davies@anu.edu.au>

.github/workflows/build.yml

@@ -12,8 +12,44 @@ permissions:
   id-token: write
 
 jobs:
+  render:
+    runs-on: self-hosted
+    container:
+      image: firedrakeproject/firedrake:latest
+      options: --shm-size 2g
+
+    env:
+      OMP_NUM_THREADS: 1
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          repository: g-adopt/tutorials
+          ref: angus-g/website-deploy
+          path: tutorials
+      - name: Install dependencies
+        run: |
+          sudo apt update
+          sudo apt install -y libgl1-mesa-glx xvfb
+          . /home/firedrake/firedrake/bin/activate
+          python3 -m pip install nbval pyvista nbconvert
+          python3 -m pip install gadopt[optimisation]
+      - name: Convert notebooks
+        run: |
+          . /home/firedrake/firedrake/bin/activate
+          export DISPLAY=:99
+          export PYVISTA_OFF_SCREEN=true
+          Xvfb $DISPLAY -screen 0 1024x768x24 > /dev/null 2>&1 &
+          sleep 3
+          python3 -m jupyter nbconvert --to notebook --execute --output-dir=rendered tutorials/*.ipynb
+      - uses: actions/upload-artifact@v4
+        with:
+          name: notebooks
+          path: rendered
+
   build:
     runs-on: ubuntu-latest
+    needs: render
     steps:
       - uses: actions/checkout@v4
       - uses: actions/setup-python@v5
@@ -28,6 +64,10 @@ jobs:
         with:
           repository: g-adopt/g-adopt
           path: g-adopt
+      - uses: actions/download-artifact@v4
+        with:
+          name: notebooks
+          path: docs/tutorials
       - name: Build site
         run: |
           mkdocs build --clean

docs/tutorials.md

@@ -1,3 +1,19 @@
 # Tutorials
 
-This is a list of tutorials, gradually introducing the G-ADOPT library.
+Here, we work through a series of tutorials that systematically introduce you to
+Firedrake and the G-ADOPT library.
+
+One the first tab, we include 5 tutorials from Firedrake.
+
+1. The positive-definite Helmholtz equation.
+2. Strong (Dirichlet) boundary conditions.
+3. Linear elasticity.
+4. A time-dependent problem using Burgers equation.
+5. PDE constrained optimisation.
+
+On the second tab, we include 2 tutorials that are specific to G-ADOPT.
+
+1. Idealised 2-D mantle convection in a square box.
+2. 2-D annulus case.
+
+We will add to these tutorials over time.

mkdocs.yml

@@ -44,13 +44,25 @@ plugins:
             members_order: source
           import:
             - https://fenics.readthedocs.io/projects/ufl/en/latest/objects.inv
+  - mkdocs-jupyter:
+      toc_depth: 2
 nav:
   - Home:
       - index.md
       - About: about.md
   - Install: install.md
   - Documentation: documentation.md
-  - Tutorials: tutorials.md
+  - Tutorials:
+    - tutorials.md
+    - Firedrake:
+      - Helmholtz: tutorials/01-spd-helmholtz.ipynb
+      - Poisson: tutorials/02-poisson.ipynb
+      - Elasticity: tutorials/03-elasticity.ipynb
+      - "Burgers' Equation": tutorials/04-burgers.ipynb
+      - PDE Constrained Optimisation: tutorials/05-pde-constrained-optimisation.ipynb
+    - G-ADOPT:
+      - Stokes Square Convection: tutorials/06-GD-2D-convection.ipynb
+      - Stokes Cylindrical Convection: tutorials/07-GD-2D-cylindrical.ipynb
   - Benchmarks: benchmarks.md
   - Team: team.md
   - Funding: funding.md

requirements.txt

@@ -2,3 +2,4 @@ mkdocs~=1.5.3
 mkdocs-material~=9.5.8
 mkdocs-glightbox~=0.3.7
 mkdocstrings[python]~=0.24.0
+mkdocs-jupyter~=0.24.7