From 28eb5e31e21faf389e0a343370bea3f74dba2e99 Mon Sep 17 00:00:00 2001 From: Max Date: Thu, 29 Oct 2026 23:28:28 +0100 Subject: [PATCH] Merge Tutorials and Full examples into one Examples section. --- .github/workflows/docs.yml | 16 +++++++------- Makefile | 6 +++--- docs/.gitignore | 8 +++---- docs/astro.config.mjs | 14 ++++++------- docs/package.json | 3 +++ docs/src/content/docs/development/docs.md | 21 ++++++++++++------- .../content/docs/development/publishing.md | 2 +- .../docs/getting-started/quickstart.md | 4 ++-- docs/src/content/docs/index.mdx | 3 +-- docs/tools/examples.py | 17 ++++++++------- tutorials/gather_and_scatter.ipynb | 3 ++- tutorials/getting_started.ipynb | 5 +++-- tutorials/index.ipynb | 11 +++++----- tutorials/kernels.ipynb | 3 ++- tutorials/mpi_and_halos.ipynb | 3 ++- 15 files changed, 65 insertions(+), 54 deletions(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 4ccd44f..aedce5a 100644 --- a/.github/workflows/docs.yml +++ b/.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 diff --git a/Makefile b/Makefile index c59af53..4d4d498 100644 --- a/Makefile +++ b/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 diff --git a/docs/.gitignore b/docs/.gitignore index 4e58606..8955814 100644 --- a/docs/.gitignore +++ b/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/ diff --git a/docs/astro.config.mjs b/docs/astro.config.mjs index b67ce66..16f0eb8 100644 --- a/docs/astro.config.mjs +++ b/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', diff --git a/docs/package.json b/docs/package.json index 155378d..e5a1bd4 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.0", "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 83018fe..1762000 100644 --- a/docs/src/content/docs/development/docs.md +++ b/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 diff --git a/docs/src/content/docs/development/publishing.md b/docs/src/content/docs/development/publishing.md index 4a5bbc7..a095a1c 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/mpifield/. Enable GitHub Pages once in the repository settings, with "GitHub Actions" as the source. diff --git a/docs/src/content/docs/getting-started/quickstart.md b/docs/src/content/docs/getting-started/quickstart.md index 53ca176..a6294ff 100644 --- a/docs/src/content/docs/getting-started/quickstart.md +++ b/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 diff --git a/docs/src/content/docs/index.mdx b/docs/src/content/docs/index.mdx index 63b8d0b..2f41135 100644 --- a/docs/src/content/docs/index.mdx +++ b/docs/src/content/docs/index.mdx @@ -38,7 +38,6 @@ import { Card, CardGrid, LinkCard } from '@astrojs/starlight/components'; - - + diff --git a/docs/tools/examples.py b/docs/tools/examples.py index 9fd419d..271b417 100644 --- a/docs/tools/examples.py +++ b/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,7 +93,7 @@ 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")) @@ -100,13 +101,13 @@ def main() -> None: 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" ) diff --git a/tutorials/gather_and_scatter.ipynb b/tutorials/gather_and_scatter.ipynb index 7cd7023..2671ab1 100644 --- a/tutorials/gather_and_scatter.ipynb +++ b/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 diff --git a/tutorials/getting_started.ipynb b/tutorials/getting_started.ipynb index 8b6af64..43b7e5d 100644 --- a/tutorials/getting_started.ipynb +++ b/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 diff --git a/tutorials/index.ipynb b/tutorials/index.ipynb index 8a16a61..d86437c 100644 --- a/tutorials/index.ipynb +++ b/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" ] } ], diff --git a/tutorials/kernels.ipynb b/tutorials/kernels.ipynb index f0e6669..46ea898 100644 --- a/tutorials/kernels.ipynb +++ b/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 diff --git a/tutorials/mpi_and_halos.ipynb b/tutorials/mpi_and_halos.ipynb index 1ddf9a6..825826e 100644 --- a/tutorials/mpi_and_halos.ipynb +++ b/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