docs: add option to open notebook directly in Colab

.github/workflows/check-colab-notebooks.yml

@@ -0,0 +1,55 @@
+name: Check Colab notebooks
+
+on:
+  push:
+    branches: [ main ]
+    paths:
+      - 'docs/notebook_source/*.py'
+  pull_request:
+    branches: [ main ]
+    paths:
+      - 'docs/notebook_source/*.py'
+  workflow_dispatch:
+
+jobs:
+  check-colab-notebooks:
+    name: Check Colab Notebooks
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          version: "latest"
+          python-version: "3.11"
+          enable-cache: true
+
+      - name: Install dependencies
+        run: |
+          uv sync --group notebooks --group docs
+
+      - name: Generate Colab notebooks
+        run: |
+          make generate-colab-notebooks
+
+      - name: Check for differences
+        run: |
+          # Get the diff, filtering out cell ID changes (which are randomly generated)
+          # Filter out: file markers (--- and +++), and "id" lines
+          MEANINGFUL_DIFF=$(git diff docs/colab_notebooks/ | grep -E '^[+-]' | grep -v '^---' | grep -v '^+++' | grep -vE '^[+-]\s*"id": "[0-9a-fA-F]+",?$' || true)
+
+          if [ -z "$MEANINGFUL_DIFF" ]; then
+            echo "✅ Colab notebooks are up-to-date (ignoring cell ID changes)"
+          else
+            echo "❌ Colab notebooks are out of sync with source files"
+            echo ""
+            echo "The generated notebooks differ from the committed ones."
+            echo "Please run 'make generate-colab-notebooks' locally and commit the changes."
+            echo ""
+            echo "Differences found:"
+            echo "$MEANINGFUL_DIFF"
+            exit 1
+          fi

Makefile

@@ -36,6 +36,7 @@ help:
 	@echo "🛠️  Utilities:"
 	@echo "  clean                     - Remove coverage reports and cache files"
 	@echo "  convert-execute-notebooks - Convert notebooks from .py to .ipynb using jupytext"
+	@echo "  generate-colab-notebooks  - Generate Colab-compatible notebooks"
 	@echo "  serve-docs-locally        - Serve documentation locally"
 	@echo "  check-license-headers     - Check if all files have license headers"
 	@echo "  update-license-headers    - Add license headers to all files"
@@ -95,6 +96,11 @@ convert-execute-notebooks:
 	rm docs/notebook_source/*.csv
 	@echo "✅ Notebooks created in docs/notebooks/"
 
+generate-colab-notebooks:
+	@echo "📓 Generating Colab-compatible notebooks..."
+	uv run --group notebooks python docs/scripts/generate_colab_notebooks.py
+	@echo "✅ Colab notebooks created in docs/colab_notebooks/"
+
 serve-docs-locally:
 	@echo "📝 Building and serving docs..."
 	uv sync --group docs
@@ -125,4 +131,4 @@ install-dev-notebooks:
 	$(call install-pre-commit-hooks)
 	@echo "✅ Dev + notebooks installation complete!"
 
-.PHONY: clean coverage format format-check lint lint-fix test check-license-headers update-license-headers check-all check-all-fix install install-dev install-dev-notebooks
+.PHONY: clean coverage format format-check lint lint-fix test check-license-headers update-license-headers check-all check-all-fix install install-dev install-dev-notebooks generate-colab-notebooks