Merge Tutorials and Full examples into one Examples section

.github/workflows/docs.yml

@@ -31,13 +31,13 @@ jobs:
       smoke-paths: |
         getting-started/installation/index.html
         getting-started/quickstart/index.html
-        tutorials/index.html
-        tutorials/getting-started/index.html
-        tutorials/mpi-and-halos/index.html
-        tutorials/getting-started/getting_started.ipynb
-        full-examples/index.html
-        full-examples/01-cloud-in-cell-density/index.html
-        full-examples/01-cloud-in-cell-density/plot-1.png
-        full-examples/12-kernel-backends/index.html
+        examples/index.html
+        examples/getting-started/index.html
+        examples/mpi-and-halos/index.html
+        examples/getting-started/getting_started.ipynb
+        example-scripts/index.html
+        example-scripts/01-cloud-in-cell-density/index.html
+        example-scripts/01-cloud-in-cell-density/plot-1.png
+        example-scripts/12-kernel-backends/index.html
         api/mpifield/index.html
         api/mpifield/field/index.html

Makefile

@@ -34,11 +34,11 @@ 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-examples:  ## run full Python examples and generate pages with their plots
+docs-examples:  ## run the example scripts and generate pages with their plots
 	$(PYTHON) docs/tools/examples.py
 
 docs-hero:  ## redraw the home page figure (docs/src/assets/hero.svg)
@@ -59,5 +59,5 @@ docs-preview:  ## serve docs/dist
 
 docs-clean:  ## remove generated pages, assets and build output
 	$(NOTEBOOKS) clean
-	rm -rf docs/src/content/docs/full-examples docs/public/full-examples
+	rm -rf docs/src/content/docs/example-scripts docs/public/example-scripts
 	rm -rf docs/dist docs/.astro

docs/.gitignore

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

docs/astro.config.mjs

@@ -10,8 +10,7 @@ export default defineDocs({
 	pythonPackage: 'mpifield',
 	nav: [
 		{ label: 'Getting started', link: '/getting-started/installation/' },
-		{ label: 'Tutorials', link: '/tutorials/' },
-		{ label: 'Full examples', link: '/full-examples/' },
+		{ label: 'Examples', link: '/examples/' },
 		{ label: 'Development', link: '/development/docs/' },
 		{ label: 'API', link: '/api/mpifield/' },
 	],
@@ -24,12 +23,11 @@ export default defineDocs({
 			],
 		},
 		{
-			label: 'Tutorials',
-			items: [{ autogenerate: { directory: 'tutorials' } }],
-		},
-		{
-			label: 'Full examples',
-			items: [{ autogenerate: { directory: 'full-examples' } }],
+			label: 'Examples',
+			items: [
+				{ autogenerate: { directory: 'examples' } },
+				{ label: 'Scripts', items: [{ autogenerate: { directory: 'example-scripts' } }] },
+			],
 		},
 		{
 			label: 'Development',

docs/package.json

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

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

@@ -1,16 +1,21 @@
 ---
 title: Building the docs
-description: How this documentation site is built from Markdown pages, Jupyter tutorials and docstrings.
+description: How this documentation site is built from Markdown pages, Jupyter notebooks and docstrings.
 ---
 
 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.
-- **Full examples**, built from Python scripts in `examples/` by `docs/tools/examples.py`.
-  Each page shows the module docstring, the complete source file, and its Matplotlib plots.
+- **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.
+- **Example scripts**, a "Scripts" group of the Examples, built from the Python scripts in
+  `examples/` by `docs/tools/examples.py`. Each page shows the module docstring, the complete
+  source file, and its Matplotlib plots.
+
+Guides, when a project has them, are hand-written pages that explain the model or a concept;
+anything runnable belongs in the Examples.
 - **API reference**, generated from the docstrings by
   [starlight-pydocs](https://ewels.github.io/starlight-pydocs/), one page per module.
 
@@ -40,9 +45,9 @@ 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 Jupyter notebook in `tutorials/`. Tutorials are authored only as `.ipynb` files. Its first `# Heading` becomes the page title and the first
+Put a Jupyter notebook in `tutorials/`. Examples are authored only as `.ipynb` files. Its first `# Heading` becomes the page title and the first
 paragraph its description. Cell tags control the output:
 
 | Tag                | Effect                                   |
@@ -55,7 +60,7 @@ paragraph its description. Cell tags control the output:
 
 Math in `$...$` and `$$...$$` is rendered with KaTeX.
 
-## Writing full examples
+## Writing example scripts
 
 Put a Python script in `examples/` with a module docstring. Its first line becomes the page
 title and the rest becomes the description. Leave Matplotlib figures open at the end of the

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/mpifield/.
 
 Enable GitHub Pages once in the repository settings, with "GitHub Actions" as the source.

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

@@ -68,8 +68,8 @@ density = Field(
 )
 ```
 
-See the [MPI tutorial](/mpifield/tutorials/mpi-and-halos/), and the
-[full examples](/mpifield/full-examples/) for a gallery of complete scripts. The
+See the [MPI and halos](/mpifield/examples/mpi-and-halos/) example, and the
+[example scripts](/mpifield/example-scripts/) for a gallery of complete scripts. The
 [API reference](/mpifield/api/mpifield/) documents every class and function.
 
 ## Profiling

docs/src/content/docs/index.mdx

@@ -38,7 +38,6 @@ import { Card, CardGrid, LinkCard } from '@astrojs/starlight/components';
 <CardGrid>
 	<LinkCard title="Installation" href="/mpifield/getting-started/installation/" description="Install the package and its extras." />
 	<LinkCard title="Quickstart" href="/mpifield/getting-started/quickstart/" description="A field, a deposit, a gather and a plot." />
-	<LinkCard title="Tutorials" href="/mpifield/tutorials/" description="Executed notebooks, from the basics to MPI and the kernels." />
-	<LinkCard title="Full examples" href="/mpifield/full-examples/" description="A gallery of complete scripts and their plots." />
+	<LinkCard title="Examples" href="/mpifield/examples/" description="Executed notebooks and complete scripts with their outputs." />
 	<LinkCard title="API reference" href="/mpifield/api/mpifield/" description="Generated from the docstrings." />
 </CardGrid>

docs/tools/examples.py

@@ -1,4 +1,4 @@
-"""Build Full examples pages from Python scripts and their Matplotlib figures."""
+"""Build the example script pages from Python scripts and their Matplotlib figures."""
 
 from __future__ import annotations
 
@@ -21,8 +21,9 @@
 
 ROOT = DOCS.parent
 SOURCES = ROOT / "examples"
-CONTENT = DOCS / "src" / "content" / "docs" / "full-examples"
-PUBLIC = DOCS / "public" / "full-examples"
+# the "Scripts" group of the Examples section, next to the notebook pages in examples/
+CONTENT = DOCS / "src" / "content" / "docs" / "example-scripts"
+PUBLIC = DOCS / "public" / "example-scripts"
 
 
 def source_fence(code: str) -> str:
@@ -64,7 +65,7 @@ def build_example(source: Path, order: int) -> tuple[str, str]:
         filename = f"plot-{index}.png"
         plt.figure(number).savefig(output / filename, dpi=150, bbox_inches="tight")
         plots.append(
-            f"![Plot {index} from {title}](/mpifield/full-examples/{slug}/{filename})"
+            f"![Plot {index} from {title}](/mpifield/example-scripts/{slug}/{filename})"
         )
     plt.close("all")
     page = [
@@ -92,21 +93,21 @@ def build_example(source: Path, order: int) -> tuple[str, str]:
 
 
 def main() -> None:
-    """Regenerate all Full examples pages and assets."""
+    """Regenerate all example script pages and assets."""
     shutil.rmtree(CONTENT, ignore_errors=True)
     shutil.rmtree(PUBLIC, ignore_errors=True)
     examples = sorted(SOURCES.glob("*.py"))
     listing = []
     for order, source in enumerate(examples, start=1):
         title, summary = build_example(source, order)
         slug = re.sub(r"[^a-z0-9]+", "-", source.stem.lower()).strip("-")
-        listing.append(f"- [{title}](/mpifield/full-examples/{slug}/): {summary}")
+        listing.append(f"- [{title}](/mpifield/example-scripts/{slug}/): {summary}")
         print(f"[examples] {source} -> {CONTENT / slug}.mdx")
     CONTENT.mkdir(parents=True, exist_ok=True)
     (CONTENT / "index.md").write_text(
-        "---\ntitle: Full examples\ndescription: Complete Python scripts and their plots.\n"
+        "---\ntitle: Scripts\ndescription: Complete Python scripts and their plots.\n"
         "sidebar:\n  order: 0\n---\n\n"
-        "Complete Python examples are listed below. Each page shows the script and its plots.\n\n"
+        "Complete Python scripts are listed below. Each page shows the script and its plots.\n\n"
         + "\n".join(listing)
         + "\n"
     )

tutorials/gather_and_scatter.ipynb

@@ -295,7 +295,8 @@
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
    "version": "3.14.4"
-  }
+  },
+  "docs_order": 2
  },
  "nbformat": 4,
  "nbformat_minor": 5

tutorials/getting_started.ipynb

@@ -11,7 +11,7 @@
     "\n",
     "A `Field` is a grid from simgeometry plus the values on its nodes, one or several components\n",
     "per node. This page goes through the basic operations on one process; the\n",
-    "[MPI tutorial](/mpifield/tutorials/mpi-and-halos/) splits the same fields over several."
+    "[MPI and halos](/mpifield/examples/mpi-and-halos/) example splits the same fields over several."
    ]
   },
   {
@@ -194,7 +194,8 @@
   },
   "language_info": {
    "name": "python"
-  }
+  },
+  "docs_order": 1
  },
  "nbformat": 4,
  "nbformat_minor": 5

tutorials/index.ipynb

@@ -5,14 +5,15 @@
    "id": "0",
    "metadata": {},
    "source": [
-    "# Tutorials\n",
+    "# Examples\n",
     "\n",
     "Jupyter notebooks, executed when the documentation is built. Download a notebook from its page to run it yourself.\n",
     "\n",
-    "- [Getting started](/mpifield/tutorials/getting-started/): create, fill, evaluate, plot and combine fields.\n",
-    "- [Gather and scatter](/mpifield/tutorials/gather-and-scatter/): deposit markers and interpolate at them.\n",
-    "- [MPI and halos](/mpifield/tutorials/mpi-and-halos/): fields split over ranks, deposits across block edges.\n",
-    "- [The kernels](/mpifield/tutorials/kernels/): the compiled kernels, their versions, and calling them directly.\n"
+    "- [Getting started](/mpifield/examples/getting-started/): create, fill, evaluate, plot and combine fields.\n",
+    "- [Gather and scatter](/mpifield/examples/gather-and-scatter/): deposit markers and interpolate at them.\n",
+    "- [MPI and halos](/mpifield/examples/mpi-and-halos/): fields split over ranks, deposits across block edges.\n",
+    "- [The kernels](/mpifield/examples/kernels/): the compiled kernels, their versions, and calling them directly.\n",
+    "- [Scripts](/mpifield/example-scripts/) are complete Python scripts with their plots.\n"
    ]
   }
  ],

tutorials/kernels.ipynb

@@ -175,7 +175,8 @@
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
    "version": "3.14.4"
-  }
+  },
+  "docs_order": 4
  },
  "nbformat": 4,
  "nbformat_minor": 5

tutorials/mpi_and_halos.ipynb

@@ -179,7 +179,8 @@
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
    "version": "3.14.4"
-  }
+  },
+  "docs_order": 3
  },
  "nbformat": 4,
  "nbformat_minor": 5