Add open-data example notebooks for interp2poi and interp2grid

.gitignore

@@ -69,6 +69,7 @@ instance/
 
 # Sphinx documentation
 doc/_build/
+doc/jupyter_execute/
 
 # PyBuilder
 target/

CHANGELOG.rst

@@ -6,6 +6,8 @@ Unreleased
 ----------
 
 * added a ``py.typed`` marker so that type checkers use the inline type hints of ``grid-process`` (PEP 561)
+* added example notebooks to the documentation illustrating ``interp2poi`` and ``interp2grid`` with open data, with
+  their dependencies in the optional ``example`` dependency group
 
 1.0.0
 -----

doc/conf.py

@@ -1,6 +1,6 @@
 import os
 
-extensions = ["sphinx.ext.napoleon", "autoapi.extension", "sphinx.ext.viewcode"]
+extensions = ["sphinx.ext.napoleon", "autoapi.extension", "sphinx.ext.viewcode", "myst_nb"]
 
 project = "grid-process"
 copyright = "2026, MeteoSwiss"
@@ -10,7 +10,11 @@
 build_id = os.getenv("BUILD_ID", default="")
 release = f"{version}-{build_id}"
 
-exclude_patterns = ["_build"]
+exclude_patterns = ["_build", "jupyter_execute", "**.ipynb_checkpoints"]
+
+# Example notebooks are committed with their outputs: they rely on short-lived open data and credentials,
+# so they are rendered as is and never executed during the documentation build.
+nb_execution_mode = "off"
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]

doc/examples.rst

@@ -0,0 +1,33 @@
+========
+Examples
+========
+
+The following notebooks illustrate the spatial interpolation functions of :mod:`grid_process.grid_interp` with open
+data from MeteoSwiss, ECMWF, Copernicus and swisstopo. Each one compares several interpolation methods visually and
+with a runtime benchmark.
+
+The notebooks are rendered with the outputs of their last execution. Since open forecast data are only kept for a few
+days, re-running them retrieves more recent forecasts. To run them, install the extra dependencies with::
+
+    poetry install --with example
+
+The forecast and reanalysis data are downloaded with `earthkit-data <https://earthkit-data.readthedocs.io>`_. To
+keep them between sessions, enable its cache once, e.g. in ``~/.config/earthkit/data/config.yaml``::
+
+    cache-policy: user
+    user-cache-directory: /path/to/a/large/disk/earthkit-cache
+
+The ERA5-Land example additionally needs a free account on the
+`Copernicus Climate Data Store <https://cds.climate.copernicus.eu>`_, with the API token in ``~/.cdsapirc`` and the
+licence of the dataset accepted once on its download page.
+
+All data are open data under the CC BY 4.0 licence (MeteoSwiss, ECMWF, Copernicus Climate Change Service) or the
+open data terms of swisstopo. The data sources are credited in each notebook.
+
+.. toctree::
+   :maxdepth: 1
+
+   examples/01_interp2poi_icon_wind_gusts
+   examples/02_interp2poi_ifs_temperature
+   examples/03_interp2grid_era5land_precipitation
+   examples/04_interp2grid_valais_temperature