Docs: Converting Jupyter notebooks in education to marimo notebooks

.github/workflows/test_docs_snippets.yml

@@ -89,3 +89,21 @@ jobs:
 
       - name: Lint education notebooks
         run: make lint-notebooks
+
+      - name: Ensure marimo notebooks are up-to-date
+        shell: bash
+        run: |
+          uv pip install -q marimo && make build-marimo && \
+          # Add any new files that might have been generated
+          git add -A
+          # Check if there are any differences
+          if ! git diff --staged --quiet; then
+            echo "Marimo notebooks are out of date!"
+            echo "Please run 'make build-marimo' locally and commit the changes."
+            exit 1
+          else
+            echo "Marimo notebooks are up to date!"
+          fi        
+
+      - name: Lint marimo notebooks 
+        run: make lint-marimo

Makefile

@@ -64,7 +64,7 @@ lint:
 
 format:
 	uv run black dlt docs tests --extend-exclude='.*syntax_error.py|_storage/.*'
-	uv run black docs/education --ipynb --extend-exclude='.*syntax_error.py|_storage/.*'
+	uv run black docs/education/*/*.ipynb
 
 lint-snippets:
 	cd docs/tools && uv run python check_embedded_snippets.py full
@@ -96,9 +96,33 @@ lint-notebooks:
 	uv run nbqa flake8 docs/education --extend-ignore=D,F704 --max-line-length=200
 	uv run nbqa mypy docs/education \
 	--ignore-missing-imports \
-	--disable-error-code=no-redef \
 	--disable-error-code=top-level-await
 
+build-marimo:
+	# Convert all ipynb files to marimo .py files
+	for file in docs/education/*/*.ipynb; do \
+		uv run marimo convert "$$file" > "$${file%.ipynb}.py"; \
+	done
+
+	# Remove trailing spaces (including inside triple-quoted strings created by marimo convert).
+	# Black does not strip whitespace inside string literals.
+	for file in docs/education/*/*.py; do \
+		perl -p -i -e 's/[ \t]+$$//' "$$file"; \
+	done
+
+	# Expand literal tabs to 4 spaces everywhere (including inside triple-quoted strings created by marimo convert).
+	# Black doesn't convert tabs inside string literals.
+	for file in docs/education/*/*.py; do \
+		perl -p -i -e 's/\t/    /g' "$$file"; \
+	done
+
+	# Format the generated Python files
+	uv run black docs/education/*/*.py
+
+lint-marimo:
+	uv run flake8 docs/education/*/*.py --extend-ignore=D,F704 --max-line-length=200
+	uv run mypy docs/education/*/*.py
+
 # check docstrings for all important public classes and functions
 lint-docstrings:
 	uv run flake8 --count \