Render and display tutorials

[angus-g]

This branch will render and display tutorials from the https://github.com/g-adopt/tutorials repository. For development, I've set up the build.yml action to pull from the branch behind this pull request, which is where the changes to the tutorials should probably end up: g-adopt/tutorials#3.

Deployment

The pull model of incorporating the tutorials definitely isn't how things should be done for the actual deployment! I think I'll set up a time-based (weekly, or similar) Action on the tutorials repository that will run the notebooks and upload the versions with populated plots/outputs as an artifact. Then the build step of the website can just grab the latest build artifact and include that, without requiring a separate build step (which takes ages when the geodynamics notebooks are included...)

Development

For local development/testing of the notebooks' functionality and formatting, there are a couple of steps.

1. Check out the branch for this PR angus-g/tutorials
2. In your MkDocs virtual environment: re-install the project dependencies: python3 -m pip install -r requirements.txt
3. The rendered notebooks need to be placed in the docs/tutorials/ directory

To actually render the notebooks, you can install the nbconvert package, and run

python3 -m jupyter nbconvert --to notebook --execute --output-dir=<g-adopt.github.io>/docs/tutorials <notebook>.ipynb

To start with, I've included the first 5 tutorials (up to PDE Constrained Optimisation). To include further tutorials, you'll need to add them into mkdocs.yml in the nav section (the file should be a pretty good guide for the required format).

Note

As always, don't forget to clear the outputs of the notebooks before committing them to the tutorials repository!

[drhodrid]

I have pushed a few changes to this over the past week. I think it's generally good to go, but needs a few minor things:

1. I would like to see 2 tabs on the tutorials page: (i) Firedrake tutorials; (ii) G-ADOPT tutorials.
2. We need to find a way to remove exercises from the tutorials as they are rendered, with notebook magic. Ideally we could not remove these exercises from our tutorials repository, as they are useful for workshops, but I don't seem them adding any value to the webpage.
3. Over time, we need to add tutorials. In the future I would like to see: (i) an adjoint tutorial, albeit after Sia's paper is published (we have one example in the repo already, but it likely needs modification); (ii) a visco-elasticity tutorial, albeit after Will's first paper is submitted; (iii) a multi-material tutorial, using level sets.

[drhodrid]

This looks good to me. I think the only outstanding thing is ensuring that the "questions" in our tutorials are masked somehow. Once online, I will take a careful look at what we have, and further update, but I think getting this in as a starting point is a good move.

[angus-g]

I think I'm going to push this as-is, but I'll need to work on the workflow for later so our webpage deployments don't take ages.