Add DANRA tutorial notebook with pytest-nbmake

.github/workflows/install-and-test.yml

@@ -75,9 +75,24 @@ jobs:
           restore-keys: |
             ${{ runner.os }}-meps-reduced-example-data-v0.3.0
 
+      - name: Run smoke test
+        if: matrix.package_manager != 'uv'
+        run: |
+          python -c "import neural_lam; print('neural-lam imported successfully')"
+
+      - name: Run tests (excluding notebooks)
+        if: matrix.package_manager == 'uv'
       - name: Run tests
         run: |
-          pytest -vv -s --doctest-modules
+          pytest -vv -s --doctest-modules --ignore=docs/notebooks
+
+      - name: Run notebook tests
+        if: |
+          matrix.package_manager == 'uv' &&
+          (github.event_name == 'push' ||
+           contains(github.event.pull_request.labels.*.name, 'run-notebooks'))
+        run: |
+          pytest -vv -s --nbmake --nbmake-timeout=600 docs/notebooks/
 
       - name: Upload test figures
         uses: actions/upload-artifact@v4

.pre-commit-config.yaml

@@ -17,6 +17,12 @@ repos:
     hooks:
       - id: codespell
         description: Check for spelling errors
+        # codespell reads [tool.codespell] from pyproject.toml via tomllib,
+        # which is unavailable on Python <3.11 unless `tomli` is installed;
+        # on such runners the config silently fails to load. Pass --skip
+        # explicitly so it doesn't depend on that.
+        args:
+          - --skip=requirements/*,docs/notebooks/hello_world_danra.ipynb
 
   - repo: https://github.com/psf/black
     rev: 25.11.0

CHANGELOG.md

@@ -8,6 +8,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [unreleased](https://github.com/mllam/neural-lam/compare/v0.6.0...HEAD)
 
 ### Added
+- Add `hello_world_danra.ipynb` end-to-end tutorial notebook for training on DANRA, with notebook CI via `nbmake` (runs on push to main or `run-notebooks` label) [\#577](https://github.com/mllam/neural-lam/pull/577) @Sharkyii
+
 - Add `--num_sanity_val_steps` CLI argument to control sanity validation steps before training (#694)
 
 - Add `--train_steps_to_log` CLI option to log training loss for individual unroll steps, and deduplicate common prediction and loss computation steps across loops [\#674](https://github.com/mllam/neural-lam/issues/674) @GiGiKoneti

docs/notebooks/conftest.py

@@ -0,0 +1,23 @@
+# Standard library
+import subprocess
+import sys
+from pathlib import Path
+
+# Third-party
+import pytest
+
+
+@pytest.fixture(scope="session", autouse=True)
+def setup_danra_datastore():
+    """Create the DANRA zarr datastore required by hello_world_danra.ipynb."""
+    datastore_config = Path(
+        "tests/datastore_examples/mdp/danra_100m_winds/danra.datastore.yaml"
+    )
+    zarr_output = datastore_config.parent / "danra.datastore.zarr"
+
+    # Only create if it doesn't exist
+    if not zarr_output.exists():
+        subprocess.run(
+            [sys.executable, "-m", "mllam_data_prep", str(datastore_config)],
+            check=True,
+        )

docs/notebooks/create_reduced_meps_dataset.ipynb

@@ -13,7 +13,11 @@
   {
    "cell_type": "code",
    "execution_count": 2,
-   "metadata": {},
+   "metadata": {
+    "tags": [
+     "skip-execution"
+    ]
+   },
    "outputs": [],
    "source": [
     "# Standard library\n",
@@ -36,7 +40,11 @@
   {
    "cell_type": "code",
    "execution_count": null,
-   "metadata": {},
+   "metadata": {
+    "tags": [
+     "skip-execution"
+    ]
+   },
    "outputs": [],
    "source": [
     "# Load existing grid\n",
@@ -61,7 +69,11 @@
   {
    "cell_type": "code",
    "execution_count": 6,
-   "metadata": {},
+   "metadata": {
+    "tags": [
+     "skip-execution"
+    ]
+   },
    "outputs": [],
    "source": [
     "# Outer 10 grid points are border\n",
@@ -91,7 +103,11 @@
   {
    "cell_type": "code",
    "execution_count": null,
-   "metadata": {},
+   "metadata": {
+    "tags": [
+     "skip-execution"
+    ]
+   },
    "outputs": [],
    "source": [
     "# Load surface_geopotential.npy, index only values from the reduced grid, and save to new file\n",
@@ -124,7 +140,11 @@
   {
    "cell_type": "code",
    "execution_count": null,
-   "metadata": {},
+   "metadata": {
+    "tags": [
+     "skip-execution"
+    ]
+   },
    "outputs": [],
    "source": [
     "num_vars = 8\n",
@@ -162,7 +182,11 @@
   {
    "cell_type": "code",
    "execution_count": 12,
-   "metadata": {},
+   "metadata": {
+    "tags": [
+     "skip-execution"
+    ]
+   },
    "outputs": [
     {
      "name": "stdout",
@@ -188,7 +212,11 @@
   {
    "cell_type": "code",
    "execution_count": null,
-   "metadata": {},
+   "metadata": {
+    "tags": [
+     "skip-execution"
+    ]
+   },
    "outputs": [],
    "source": [
     "for sample in ['train', 'test', 'val']:\n",