Add notebooks to GitHub actions

.github/workflows/notebooks.yml

@@ -0,0 +1,75 @@
+name: Notebook Tests
+
+on: [push]
+
+jobs:
+  tests:
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 30
+    strategy:
+      matrix:
+        os: [ubuntu-latest]
+        mpi: ["none"]
+        python: ["3.10"]
+
+    # Only run notebook tests if there is no [skipnb] or [skip nb] in the commit message
+    if: |
+      !startsWith(github.event.head_commit.message, '[skip nb]') &&
+      !startsWith(github.event.head_commit.message, '[skipnb]') &&
+      !startsWith(github.event.head_commit.message, '[skip ci]') &&
+      !startsWith(github.event.head_commit.message, '[skipci]')
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v7
+
+      - name: Setup Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python }}
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          python-version: ${{ matrix.python }}
+          enable-cache: true
+          save-cache: false
+          prune-cache: false
+          cache-dependency-glob: |
+            pyproject.toml
+            uv.lock
+
+      - name: Restore virtual environment
+        uses: actions/cache/restore@v6
+        with:
+          path: .venv
+          key: venv-${{ runner.os }}-${{ matrix.python }}-${{ matrix.mpi }}-${{ secrets.CACHE_VERSION }}-${{ hashFiles('pyproject.toml') }}-${{ hashFiles('uv.lock') }}
+
+      - name: Restore PySM3 data files
+        id: cache-pysm3
+        uses: actions/cache/restore@v6
+        with:
+          path: ~/pysm3-data
+          key: pysm3-data-${{ runner.os }}-${{ matrix.python }}-${{ matrix.mpi }}-${{ secrets.CACHE_VERSION }}
+
+      - name: Register PySM3 data path
+        run: |
+          echo "PYSM_LOCAL_DATA=$HOME/pysm3-data" >> $GITHUB_ENV
+
+      - name: Download PySM3 data files
+        if: steps.cache-pysm3.outputs.cache-hit != 'true'
+        run: git clone --depth 1 https://github.com/galsci/pysm-data "$PYSM_LOCAL_DATA"
+
+      - name: Install basic dependencies (FFTW, IMO)
+        run: |
+          ./bin/install-deps.sh ${{ matrix.mpi }}
+          mkdir -p $HOME/.config/litebird_imo
+          echo -e "[[repositories]]\nlocation = \"$(pwd)/test/mock_imo/\"\nname = \"Mock IMO\"" | tee $HOME/.config/litebird_imo/imo.toml
+
+      - name: Install litebird_sim dependencies
+        run: uv sync --extra dev --extra docs --locked
+        env:
+          DUCC0_OPTIMIZATION: none
+
+      - name: Notebook Tests
+        run: uv run python -m pytest --nbmake -n auto --durations=5 -vv notebooks/*.ipynb

.gitignore

@@ -149,6 +149,10 @@ singularity/*.img
 
 # The documentation converted to any format should not be committed
 docs/build/
+# Written by the doctests in docs/source/tutorial.rst
+docs/tut02/
+# Notebooks copied in by docs/source/conf.py
+docs/source/tutorials/
 
 # Claude Code stuff
 /.claude

.pre-commit-config.yaml

@@ -22,3 +22,11 @@ repos:
     # Run the formatter.
     - id: ruff-format
       types_or: [ python, pyi, jupyter ]
+- repo: https://github.com/kynan/nbstripout
+  # Keeps the notebook outputs (they are what gets rendered in the docs) but
+  # strips execution counts and kernel metadata, which otherwise churn on every
+  # re-run and make notebook diffs unreadable.
+  rev: 0.9.1
+  hooks:
+    - id: nbstripout
+      args: ["--keep-output", "--extra-keys", "metadata.kernelspec metadata.language_info.version"]

docs/source/conf.py

@@ -11,12 +11,19 @@
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 
 import os
+import shutil
 import sys
 from pathlib import Path
 
 sys.path.insert(0, os.path.abspath(os.path.join("..", "..")))
 sys.path.append(str(Path("_ext").resolve()))
 
+_notebook_src = Path(__file__).parent.parent.parent / "notebooks"
+_notebook_dst = Path(__file__).parent / "tutorials"
+_notebook_dst.mkdir(exist_ok=True)
+for _nb in _notebook_src.glob("*.ipynb"):
+    shutil.copy2(_nb, _notebook_dst / _nb.name)
+
 # -- Project information -----------------------------------------------------
 
 project = "LBS"
@@ -40,8 +47,11 @@
     "sphinx.ext.napoleon",
     "sphinxcontrib.contentui",
     "matplotlib.sphinxext.plot_directive",
+    "myst_nb",
 ]
 
+nb_execution_mode = "off"
+
 bibtex_bibfiles = ["refs.bib"]
 
 

docs/source/hwp_sys.rst

@@ -148,8 +148,8 @@ Examples
 -------------
 
 Examples can be seen in the notebooks:
-    1 - `Performing a simulation with explicit HWP harmonics expansion <https://github.com/litebird/litebird_sim/blob/master/notebooks/litebird_sim_hwp_harmonics_example.ipynb>`_
-    2 - `Performing band integration with a Jones Matrix <https://github.com/litebird/litebird_sim/blob/master/notebooks/litebird_sim_hwp_band_integration.ipynb>`_
+    1 - :doc:`Performing a simulation with explicit HWP harmonics expansion <tutorials/litebird_sim_hwp_harmonics_example>`
+    2 - :doc:`Performing band integration with a Jones Matrix <tutorials/litebird_sim_hwp_band_integration>`
 
 
 

docs/source/notebooks.rst

@@ -0,0 +1,16 @@
+.. _tutorial_notebooks:
+
+Example notebooks
+=================
+
+The following Jupyter notebooks are shipped in the ``notebooks/`` folder of
+the repository. They are rendered here with the outputs produced when they
+were last run, and they are executed on every push by the ``Notebook Tests``
+workflow, so the code in them is guaranteed to run against the current
+version of the framework.
+
+.. toctree::
+   :maxdepth: 1
+   :glob:
+
+   tutorials/*

docs/source/part6.rst

@@ -5,3 +5,4 @@ Tutorials
    :maxdepth: 1
 
    tutorial.rst
+   notebooks.rst

docs/source/tutorial.rst

@@ -6,9 +6,10 @@ Tutorial
 This section contains a short tutorial that describes how to get ready
 to use the framework. It assumes that you have already installed the
 ``litebird_sim`` framework; refer to :ref:`installation_procedure`.
-For a nice and exhaustive example on how to use the framework in the 
-LiteBIRD case see the `example notebook <https://github.com/litebird
-/litebird_sim/blob/master/notebooks/litebird_sim_example.ipynb>`_.
+For a nice and exhaustive example on how to use the framework in the
+LiteBIRD case see :doc:`the example notebook
+<tutorials/litebird_sim_example>`, and :ref:`tutorial_notebooks` for the
+other notebooks shipped with the framework.
 
 A «Hello world» example
 -----------------------