Merge Tutorials and Full examples into one Examples section

.github/workflows/docs.yml

@@ -27,5 +27,5 @@ jobs:
       node-version: "24"
       smoke-paths: |
         getting-started/installation/index.html
-        tutorials/01-first-hierarchy/index.html
+        examples/01-first-hierarchy/index.html
         api/patchwork/index.html

Makefile

@@ -34,7 +34,7 @@ docs-install:  ## Python docs extra and the npm packages
 	$(PYTHON) -m pip install -e ".[docs]"
 	cd docs && npm ci
 
-docs-notebooks:  ## execute the changed tutorials and convert all of them (FORCE=1 reruns all)
+docs-notebooks:  ## execute the changed notebooks and convert all of them (FORCE=1 reruns all)
 	$(NOTEBOOKS) execute $(if $(FORCE),--force,)
 	$(NOTEBOOKS) convert
 

docs/.gitignore

@@ -4,5 +4,5 @@ dist/
 node_modules/
 # generated by starlight-notebooks (regenerated in CI)
 .cache/
-public/tutorials/
-src/content/docs/tutorials/*.mdx
+public/examples/
+src/content/docs/examples/*.mdx

docs/astro.config.mjs

@@ -10,7 +10,7 @@ export default defineDocs({
 	pythonPackage: 'patchwork',
 	nav: [
 		{ label: 'Getting started', link: '/getting-started/installation/' },
-		{ label: 'Tutorials', link: '/tutorials/' },
+		{ label: 'Examples', link: '/examples/' },
 		{ label: 'Development', link: '/development/docs/' },
 		{ label: 'API', link: '/api/patchwork/' },
 	],
@@ -23,8 +23,8 @@ export default defineDocs({
 			],
 		},
 		{
-			label: 'Tutorials',
-			items: [{ autogenerate: { directory: 'tutorials' } }],
+			label: 'Examples',
+			items: [{ autogenerate: { directory: 'examples' } }],
 		},
 		{
 			label: 'Development',

docs/package.json

@@ -20,5 +20,8 @@
     "@max-models/starlight-theme": "github:max-models/starlight-theme#v0.6.0",
     "astro": "^7.4.2",
     "sharp": "^0.35.3"
+  },
+  "starlight-notebooks": {
+    "section": "examples"
   }
 }

docs/src/content/docs/development/docs.md

@@ -7,8 +7,9 @@ The site in `docs/` is built with [Astro](https://astro.build/) and
 [Starlight](https://starlight.astro.build/). It has three kinds of pages:
 
 - **Hand-written pages** in `docs/src/content/docs/`, as Markdown or MDX.
-- **Tutorials**, converted from the Jupyter notebooks in `tutorials/` by `starlight-notebooks`.
-  Each notebook is executed and its outputs (text, images, tables) are written into an MDX page.
+- **Examples**, converted from the Jupyter notebooks in `tutorials/` by `starlight-notebooks`
+  (the `section` setting in `docs/package.json` publishes them under `examples/`). Each
+  notebook is executed and its outputs (text, images, tables) are written into an MDX page.
 - **API reference**, generated from the docstrings by
   [starlight-pydocs](https://ewels.github.io/starlight-pydocs/), one page per module.
 
@@ -37,7 +38,7 @@ make docs-clean       # remove generated pages and build output
 `make docs-notebooks` only reruns a notebook whose cells changed since the last run; pass
 `FORCE=1` to rerun all of them.
 
-## Writing tutorials
+## Writing example notebooks
 
 Put a notebook in `tutorials/`. Its first `# Heading` becomes the page title and the first
 paragraph its description. Cell tags control the output:

docs/src/content/docs/development/publishing.md

@@ -6,7 +6,7 @@ description: Publish the package to PyPI and the documentation to GitHub Pages.
 ## Documentation
 
 The `Docs` workflow builds the site on every push and pull request to `main` and `devel`. It
-executes the tutorials, generates the API reference and uploads the site. Pushes to `devel`
+executes the notebooks, generates the API reference and uploads the site. Pushes to `devel`
 also deploy it to GitHub Pages at https://max-models.github.io/patchwork/.
 
 Enable GitHub Pages once in the repository settings, with "GitHub Actions" as the source.

docs/src/content/docs/tutorials/index.md → docs/src/content/docs/examples/index.md

@@ -1,25 +1,26 @@
 ---
-title: Tutorials
+title: Examples
 description: Notebooks from the tutorials directory, executed and published with their outputs.
 sidebar:
   order: 0
 ---
 
 Step by step, from a first hierarchy to stencils on patches:
 
-1. [A first patch hierarchy](/patchwork/tutorials/01-first-hierarchy/): the base level,
+1. [A first patch hierarchy](/patchwork/examples/01-first-hierarchy/): the base level,
    patches and the rules they follow, cell- and node-centered fields.
-2. [Poisson's equation on cells](/patchwork/tutorials/02-cell-centered-poisson/): the
+2. [Poisson's equation on cells](/patchwork/examples/02-cell-centered-poisson/): the
    conservative cell-centered solve and its convergence.
-3. [Poisson's equation on nodes](/patchwork/tutorials/03-node-centered-poisson/): faces with
+3. [Poisson's equation on nodes](/patchwork/examples/03-node-centered-poisson/): faces with
    different conditions, periodic axes, electrodes, solving again, uniform-grid maps, and
    the solver backends (LU, FFT, PETSc).
-4. [Domains that are not rectangles](/patchwork/tutorials/04-non-rectangular-domains/): an L
+4. [Domains that are not rectangles](/patchwork/examples/04-non-rectangular-domains/): an L
    and a T, with patches at their inner corners.
-5. [Halos: stencils on patches](/patchwork/tutorials/05-halo-exchange/): halo exchange and
+5. [Halos: stencils on patches](/patchwork/examples/05-halo-exchange/): halo exchange and
    restriction.
-6. [Regridding](/patchwork/tutorials/06-regridding/): tagging cells, clustering them into
+6. [Regridding](/patchwork/examples/06-regridding/): tagging cells, clustering them into
    patches, and patches that follow a moving feature.
+7. [Edge space](/patchwork/examples/07-edge-space/): the electric-field space on the edges of the leaf cells.
 
 Every notebook in `tutorials/` is executed when the site is built and published here with its
 outputs. Download a notebook from its page to run the steps yourself.

docs/src/content/docs/getting-started/quickstart.md

@@ -43,7 +43,7 @@ The composite Poisson example solves a smooth source across the coarse-fine inte
 ![Composite Poisson solution on a refined patch](/patchwork/figures/composite_poisson.png)
 For nested levels and a complete script, run `python examples/nested_patches.py`.
 
-The [tutorials](/patchwork/tutorials/) go further, step by step: fields on patches, the
+The [examples](/patchwork/examples/) go further, step by step: fields on patches, the
 cell-centered and node-centered Poisson solves (faces with different conditions, periodic
 axes, electrodes), domains that are not rectangles, halos, and regridding.
 

docs/src/content/docs/index.mdx

@@ -38,6 +38,6 @@ import { Card, CardGrid, LinkCard } from '@astrojs/starlight/components';
 <CardGrid>
 	<LinkCard title="Installation" href="/patchwork/getting-started/installation/" description="Install Patchwork and its optional plotting tools." />
 	<LinkCard title="Quickstart" href="/patchwork/getting-started/quickstart/" description="Create and plot a two-level mesh." />
-	<LinkCard title="Tutorials" href="/patchwork/tutorials/" description="Executed notebooks with their outputs." />
+	<LinkCard title="Examples" href="/patchwork/examples/" description="Executed notebooks with their outputs." />
 	<LinkCard title="API reference" href="/patchwork/api/patchwork/" description="Generated from the docstrings." />
 </CardGrid>

tutorials/01_first_hierarchy.ipynb

@@ -8,7 +8,7 @@
     "# Patch hierarchy\n",
     "\n",
     "A hierarchy is a coarse base mesh and rectangular patches of finer cells on top of it. This\n",
-    "tutorial builds one, shows the rules the patches follow, and puts fields on it."
+    "notebook builds one, shows the rules the patches follow, and puts fields on it."
    ]
   },
   {

tutorials/02_cell_centered_poisson.ipynb

@@ -103,7 +103,7 @@
    "metadata": {},
    "source": [
     "For faces with different conditions, periodic axes or electrodes inside the domain,\n",
-    "use the node-centered solver of the next tutorial."
+    "use the node-centered solver of the next example."
    ]
   }
  ],