execute.yaml

name: Execute notebooks

on:
  schedule:
    # Weekly: Mondays 04:00 UTC; re-executes ALL notebooks against latest releases.
    - cron: "0 4 * * 1"
  pull_request:
    branches: [main]
    paths:
      - "**/*.ipynb"
      - "pyproject.toml"
      - ".github/workflows/execute.yaml"
  workflow_dispatch:

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

jobs:
  execute:
    runs-on: ubuntu-latest
    timeout-minutes: 60
    steps:
      - uses: actions/checkout@v5

      - uses: actions/setup-python@v5
        with:
          python-version: "3.13"
          cache: pip
          cache-dependency-path: pyproject.toml

      - name: Cache pooch datasets
        uses: actions/cache@v4
        with:
          path: ~/.cache/pooch
          # Datasets are pinned by URL inside notebook code, not by the
          # notebook's surrounding markdown — bump the v* suffix when an
          # actually-new dataset URL lands.
          key: pooch-${{ runner.os }}-v1
          restore-keys: |
            pooch-${{ runner.os }}-

      - name: Install execution environment
        run: |
          pip install --upgrade pip
          pip install -e ".[exec]"

      - name: Detect changed notebooks (PR only)
        if: github.event_name == 'pull_request'
        id: changed
        uses: tj-actions/changed-files@v45
        with:
          files: |
            tutorials/**/*.ipynb
            examples/**/*.ipynb

      - name: Determine notebooks to execute
        id: pick
        run: |
          if [ "${{ github.event_name }}" = "pull_request" ]; then
            nbs="${{ steps.changed.outputs.all_changed_files }}"
            # tj-actions emits space-separated; one-per-line for the loop below.
            nbs=$(printf '%s\n' $nbs)
          else
            nbs=$(find tutorials examples -name "*.ipynb" -not -path "*/.ipynb_checkpoints/*" 2>/dev/null || true)
          fi
          if [ -z "$nbs" ]; then
            echo "No notebooks to execute."
          else
            echo "Will execute:"
            echo "$nbs"
          fi
          {
            echo 'files<<EOF'
            echo "$nbs"
            echo 'EOF'
          } >> "$GITHUB_OUTPUT"

      - name: Re-execute selected notebooks
        if: steps.pick.outputs.files != ''
        run: |
          # Pin kernel_name to python3 so notebooks committed with a
          # contributor-local kernel name (e.g. from a pixi `kernel-install`
          # task) still execute against CI's stock python3 kernel.
          while IFS= read -r nb; do
            [ -z "$nb" ] && continue
            echo "Executing $nb"
            jupyter nbconvert --to notebook --execute --inplace \
              --ExecutePreprocessor.kernel_name=python3 "$nb"
          done <<< "${{ steps.pick.outputs.files }}"