Adding a tutorial

Adding a tutorial#

Put the notebook under tutorials/ and give it this notebook metadata, then run python docs/scripts/generate_tutorial_index.py (CI does):

"zoomy": {"title": "...", "summary": "<one line>", "tags": ["type:tutorial", "dimension:1d", "physics:viscous"]}

Tags are category:value; an unknown tag or a missing type fails the build. A notebook may carry several values of one category (except type).

  • type: tutorial / use-case (required)

  • dimension: 1d / 2d / 3d

  • physics: viscous / inviscid / hydrostatic / non-hydrostatic / compressible / incompressible / free-surface

  • component: model / system-model / numerical-system-model / solver / code-generation / mesh

  • method: finite-volume / limiting / implicit-explicit / predictor-corrector

  • feature: automatic-differentiation / parallel / gpu / coupling / function-hook

  • backend: numpy / jax / openfoam / amrex

requires: cpu / gpu / mpi / container is no filter. It tells the test harness what the notebook needs (default requires:cpu): pytest tests/tutorials -m tutorial executes every notebook that needs only the CPU and reports the others as skipped.

The book renders every notebook that has a card, from a copy in docs/book/tutorials/ipynb/ (git-ignored); a notebook under tutorials/pyodide/ is the content of the JupyterLite deployment and its card links there.