Add GitHub Action to generate .py mirrors from notebooks (jupytext)

Per Peter Norvig's suggestion on #1340 ('use a github action to generate a .py
file from a notebook every time the notebook is edited'):

- .github/workflows/notebooks-to-py.yml: on every push to master that touches a
  notebook, regenerate a readable py:percent mirror of each notebooks/**/*.ipynb
  with jupytext and commit the result (also prunes mirrors of deleted notebooks).
  One-way only — it never touches the hand-maintained aima/ package. Loop-safe
  (the commit changes only *.py, which doesn't match the .ipynb path trigger;
  plus [skip ci]).
- Committed the initial .py mirrors for all notebooks so the repo starts in sync.
- README/CONTRIBUTING: document that the .ipynb is the source of truth and the
  .py mirror is generated (don't hand-edit it); also fixed the stale bootstrap
  description (now '%run bootstrap.ipynb', no chdir).

Author: dmeoli

.github/workflows/notebooks-to-py.yml

@@ -0,0 +1,59 @@
+name: Notebooks → .py
+
+# Per Peter Norvig's suggestion (PR #1340): the .ipynb notebooks are the source
+# of truth; this action regenerates a readable, diffable .py mirror of each one
+# (via jupytext, py:percent) every time a notebook is edited on master, and
+# commits the result. It only writes notebooks/**/*.py — it never touches the
+# aima/ package, which is maintained by hand.
+
+on:
+  push:
+    branches: [master]
+    paths:
+      - 'notebooks/**/*.ipynb'
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+# only one regeneration at a time; newer pushes supersede in-flight ones
+concurrency:
+  group: notebooks-to-py
+  cancel-in-progress: true
+
+jobs:
+  jupytext:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Install jupytext
+        run: pip install jupytext
+
+      - name: Generate .py mirrors from notebooks
+        run: |
+          # one-way export: each notebooks/**/X.ipynb -> notebooks/**/X.py (py:percent)
+          find notebooks -name '*.ipynb' -not -path '*/.ipynb_checkpoints/*' \
+            -exec jupytext --to py:percent {} +
+          # drop any .py whose source notebook no longer exists
+          find notebooks -name '*.py' | while read -r py; do
+            [ -f "${py%.py}.ipynb" ] || { echo "removing orphan $py"; rm -f "$py"; }
+          done
+
+      - name: Commit regenerated .py
+        run: |
+          git config user.name  "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git add -A notebooks
+          if git diff --cached --quiet; then
+            echo "notebook .py mirrors already up to date"
+          else
+            # the commit only changes *.py, which doesn't match this workflow's
+            # .ipynb path filter, so it won't retrigger; [skip ci] is belt-and-braces
+            git commit -m "Auto-generate notebook .py mirrors from edited .ipynb [skip ci]"
+            git push
+          fi

CONTRIBUTING.md

@@ -38,7 +38,7 @@ We hope to have an `algorithm-name.md` file for each algorithm, eventually; it w
 
 ## Jupyter Notebooks
 
-In this project we use Jupyter/IPython Notebooks to showcase the algorithms in the book. They serve as short tutorials on what the algorithms do, how they are implemented and how one can use them. To install Jupyter, you can follow the instructions [here](https://jupyter.org/install.html). These are some ways you can contribute to the notebooks:
+In this project we use Jupyter/IPython Notebooks to showcase the algorithms in the book. They serve as short tutorials on what the algorithms do, how they are implemented and how one can use them. To install Jupyter, you can follow the instructions [here](https://jupyter.org/install.html). Each notebook has an auto-generated `.py` mirror next to it (produced by the `notebooks-to-py.yml` GitHub Action via jupytext): the `.ipynb` is the source of truth — edit the notebook, never the generated `.py`. These are some ways you can contribute to the notebooks:
 
 - Proofread the notebooks for grammar mistakes, typos, or general errors.
 - Move visualization and unrelated to the algorithm code from notebooks to `notebook_utils.py` (a file used to store code for the notebooks, like visualization and other miscellaneous stuff). Make sure the notebooks still work and have their outputs showing!

README.md

@@ -25,7 +25,7 @@ The 4th edition of the book is out now in 2020, and thus we are updating the cod
 When complete, this project will have Python implementations for all the pseudocode algorithms in the book, as well as tests and examples of use. The code is organised into three top-level folders:
 
 - **`aima/`** — the importable Python package: one module per major topic (e.g. `aima/search.py`) with the implementations of the pseudocode algorithms and their support functions/classes/data.
-- **`notebooks/`** — the Jupyter notebooks that explain and demonstrate the code (e.g. `notebooks/search.ipynb`), plus the per-chapter `notebooks/chapterNN/` demos. Each notebook starts with a small bootstrap cell so it runs correctly from the `notebooks/` folder (it `chdir`s to the repo root so `from aima import ...` and the `aima-data/`/`images/` paths resolve).
+- **`notebooks/`** — the Jupyter notebooks that explain and demonstrate the code (e.g. `notebooks/search.ipynb`), plus the per-chapter `notebooks/chapterNN/` demos. Each notebook starts with a `%run bootstrap.ipynb` cell that puts the repo root on `sys.path`, so `from aima import ...` works wherever the notebook is launched. A GitHub Action ([`notebooks-to-py.yml`](.github/workflows/notebooks-to-py.yml)) keeps a readable, diffable `.py` mirror of every notebook beside it (generated with [jupytext](https://jupytext.readthedocs.io)); the `.ipynb` is the source of truth, so edit the notebook, not the generated `.py`.
 - **`tests/`** — a lightweight test suite (e.g. `tests/test_search.py`), using `assert` statements, designed for use with [`py.test`](http://pytest.org/latest/) but also usable on their own.
 
 # Python 3.9 and up