From e7d49ec06de8c4abd3b867fdd828b0bcacf4b64c Mon Sep 17 00:00:00 2001 From: Max Date: Thu, 29 Oct 2026 23:29:07 +0100 Subject: [PATCH] Merge Tutorials and Full examples into one Examples section. --- .github/workflows/docs.yml | 2 +- Makefile | 2 +- docs/.gitignore | 4 ++-- docs/astro.config.mjs | 6 +++--- docs/package.json | 3 +++ docs/src/content/docs/development/docs.md | 7 ++++--- docs/src/content/docs/development/publishing.md | 2 +- .../content/docs/{tutorials => examples}/index.md | 15 ++++++++------- .../content/docs/getting-started/quickstart.md | 2 +- docs/src/content/docs/index.mdx | 2 +- tutorials/01_first_hierarchy.ipynb | 2 +- tutorials/02_cell_centered_poisson.ipynb | 2 +- 12 files changed, 27 insertions(+), 22 deletions(-) rename docs/src/content/docs/{tutorials => examples}/index.md (55%) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 35dda8b..23413a6 100644 --- a/.github/workflows/docs.yml +++ b/.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 diff --git a/Makefile b/Makefile index 0ecac3a..72f9754 100644 --- a/Makefile +++ b/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 diff --git a/docs/.gitignore b/docs/.gitignore index 2a97a9b..d340f5a 100644 --- a/docs/.gitignore +++ b/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 diff --git a/docs/astro.config.mjs b/docs/astro.config.mjs index 6342ac2..f5e62ef 100644 --- a/docs/astro.config.mjs +++ b/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', diff --git a/docs/package.json b/docs/package.json index 8b84af5..ec9bdc7 100644 --- a/docs/package.json +++ b/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" } } diff --git a/docs/src/content/docs/development/docs.md b/docs/src/content/docs/development/docs.md index cbbeb2c..aa004ac 100644 --- a/docs/src/content/docs/development/docs.md +++ b/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: diff --git a/docs/src/content/docs/development/publishing.md b/docs/src/content/docs/development/publishing.md index f87aabc..a191884 100644 --- a/docs/src/content/docs/development/publishing.md +++ b/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. diff --git a/docs/src/content/docs/tutorials/index.md b/docs/src/content/docs/examples/index.md similarity index 55% rename from docs/src/content/docs/tutorials/index.md rename to docs/src/content/docs/examples/index.md index 700df81..1398655 100644 --- a/docs/src/content/docs/tutorials/index.md +++ b/docs/src/content/docs/examples/index.md @@ -1,5 +1,5 @@ --- -title: Tutorials +title: Examples description: Notebooks from the tutorials directory, executed and published with their outputs. sidebar: order: 0 @@ -7,19 +7,20 @@ sidebar: 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. diff --git a/docs/src/content/docs/getting-started/quickstart.md b/docs/src/content/docs/getting-started/quickstart.md index 1d06d27..0f1af82 100644 --- a/docs/src/content/docs/getting-started/quickstart.md +++ b/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. diff --git a/docs/src/content/docs/index.mdx b/docs/src/content/docs/index.mdx index 9fc2e30..0e66b84 100644 --- a/docs/src/content/docs/index.mdx +++ b/docs/src/content/docs/index.mdx @@ -38,6 +38,6 @@ import { Card, CardGrid, LinkCard } from '@astrojs/starlight/components'; - + diff --git a/tutorials/01_first_hierarchy.ipynb b/tutorials/01_first_hierarchy.ipynb index 78d7911..39e258d 100644 --- a/tutorials/01_first_hierarchy.ipynb +++ b/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." ] }, { diff --git a/tutorials/02_cell_centered_poisson.ipynb b/tutorials/02_cell_centered_poisson.ipynb index 642501c..f343bb8 100644 --- a/tutorials/02_cell_centered_poisson.ipynb +++ b/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." ] } ],