lets sync with mothership

.github/workflows/build-and-deploy.yml

@@ -38,11 +38,11 @@ jobs:
         uses: actions/checkout@v4.1.7
 
       - name: apt installs
-        run: sudo apt update && sudo apt install -y texlive-latex-extra texlive-lang-cyrillic ghostscript
+        run: sudo apt update && sudo apt install -y texlive-latex-extra texlive-lang-cyrillic ghostscript libenchant-2-dev
 
-      - uses: actions/setup-python@v5.1.0
+      - uses: actions/setup-python@v6.2.0
         with:
-          python-version: '3.10'
+          python-version: '3.12'
 
       - name: pip installs
         run: pip install -r requirements.txt
@@ -97,14 +97,24 @@ jobs:
         env:
           CREATOR_ID: ${{ secrets.CREATOR_ID }}
 
+      # Build a self-hosted JupyterLite environment into _build/jupyterlite so the
+      # interactive "run this code" links in the book point at our own deployment
+      # rather than a third-party demo site. Done last so its pip installs can't
+      # disturb the Sphinx builds above.
+      - name: Build JupyterLite
+        run: |
+          pip install -r requirements-jupyterlite.txt
+          jupyter lite build --contents jupyterlite --output-dir _build/jupyterlite
+          python jupyterlite/inject_branding.py _build/jupyterlite
+
       - name: Upload artifact
         uses: actions/upload-pages-artifact@v3.0.1
         with:
           path: './_build'
 
       - name: Deploy to GitHub Pages
         id: deployment
-        uses: actions/deploy-pages@v4.0.5
+        uses: actions/deploy-pages@v5.0.0
 
       - name: Get current date
         id: date

.github/workflows/build-and-spell-check.yml

@@ -10,11 +10,11 @@ jobs:
         uses: actions/checkout@v4.1.7
 
       - name: apt installs
-        run: sudo apt update && sudo apt install -y texlive-latex-extra texlive-lang-cyrillic ghostscript
+        run: sudo apt update && sudo apt install -y texlive-latex-extra texlive-lang-cyrillic ghostscript libenchant-2-dev
 
-      - uses: actions/setup-python@v5.1.0
+      - uses: actions/setup-python@v6.2.0
         with:
-          python-version: '3.10'
+          python-version: '3.12'
 
       - name: pip installs
         run: pip install -r requirements.txt

.vscode/settings.json

@@ -1,80 +1,9 @@
 {
     "esbonio.sphinx.confDir": "",
-    "cSpell.words": [
-        "arange",
-        "argmax",
-        "argsort",
-        "asarray",
-        "asmatrix",
-        "astype",
-        "AWGN",
-        "baseband",
-        "beamformer",
-        "beamformers",
-        "beamforming",
-        "boresight",
-        "bpsk",
-        "bytearray",
-        "CDMA",
-        "checkword",
-        "convolutional",
-        "Costas",
-        "datacast",
-        "dataword",
-        "demod",
-        "downconversion",
-        "dtype",
-        "endfire",
-        "Ettus",
-        "figsize",
-        "fillmein",
-        "firwin",
-        "fontsize",
-        "fromfile",
-        "Gbps",
-        "imag",
-        "lastseen",
-        "leftrightarrow",
-        "lfilter",
-        "linalg",
-        "linspace",
-        "mathrm",
-        "matplotlib",
-        "Mbps",
-        "mlen",
-        "multipath",
-        "MVDR",
-        "numpy",
-        "numtaps",
-        "Nyquist",
-        "OFDM",
-        "pinv",
-        "plen",
-        "postcostas",
-        "presync",
-        "pyplot",
-        "QPSK",
-        "radiotext",
-        "randint",
-        "randn",
-        "rgrids",
-        "Rinv",
-        "rlabel",
-        "savefig",
-        "scipy",
-        "thetamax",
-        "thetamin",
-        "Uplif",
-        "USRP",
-        "webp",
-        "wirelessly",
-        "xdata",
-        "xlabel",
-        "ydata",
-        "ylabel"
-    ],
     "githubPullRequests.ignoredPullRequestBranches": [
         "master"
     ],
-    "python.analysis.typeCheckingMode": "basic"
+    "python.analysis.typeCheckingMode": "basic",
+    "editor.formatOnSave": false,
+    "editor.wordWrap": "on"
 }

AGENTS.md

@@ -0,0 +1,66 @@
+# Repository Guidance for AI Contributors
+
+This repo is the source for the PySDR textbook, created using Sphinx.  
+
+## Human Notes
+
+This section is for human reference only. It is not an instruction for agents and should not change behavior.
+
+Marc uses AI to help create the JavaScript mini-apps and solve issues like when certain things are not rendered correctly, he doesn't use it to write the actual content, other than spelling/grammar edits and scanning for bugs/incorrectness. 
+
+## What to edit
+
+- Edit the `.rst` files under `content/` and the Sphinx config/templates under the repo root.
+- Treat `_build/` as generated output. Do not edit it directly.
+- Images (primarily in SVG format) referenced by the RST live in _images/
+- Python code used to produce images (primarily in SVG format) lives in figure-generating-scripts/
+- If you change a page, also check whether image assets, scripts, or config in `_static/`, `_images/`, `conf.py`, or `Makefile` need matching updates.
+
+## How to build locally
+
+If the prompt does not ask to build it, then don't build it.
+
+- Activate the project virtual environment which should be in the root of this repo under .venv
+
+- Build the site using:
+
+```bash
+make fast-html
+```
+
+- The rendered HTML site will be in `_build/`.
+- Open `_build/index.html` for the main site, or the relevant page under `_build/content/`.
+
+## Practical workflow
+
+- Make the source change.
+- Run `make fast-html`.
+- Inspect the generated HTML in `_build/` to verify the result.
+- Keep changes minimal and aligned with the existing textbook style.
+
+## Writing Style
+
+Note to humans- This guidance is provided to AI to help edit, not actually write material, Marc's writes everything himself then uses AI for catching grammar issues and such.
+
+PySDR's prose is intentionally instructional, conversational, and example-driven. When editing chapter text, match these patterns:
+
+- Start with intuition before formalism. Explain the idea in plain language first, then introduce equations or code.
+- Prefer short, direct paragraphs. Long sections are acceptable, but they should be broken up with transitions, examples, or figures.
+- Use first-person plural sparingly but naturally (`we`, `let's`) to guide the reader through the material.
+- Keep the tone approachable and lightly informal, but not casual or chatty.
+- Use rhetorical questions and plain-English restatements when they help clarify a concept.
+- Explain why a step matters, not just what the step is.
+- Preserve the textbook’s teaching rhythm: concept, example, code, result, takeaway.
+- Keep technical terminology precise, but avoid sounding overly academic or formal.
+- When a section already has figures or code, make the surrounding prose point the reader to them and explain what they should notice.
+- Avoid hype, filler, and motivational fluff.
+- Lead with a concrete scenario before any equation. Pose a small "what if" with real numbers (e.g. "the emitter is 100 m closer to one sensor"), then generalize. Introduce the named concept (hyperbola, foci) in plain words before showing the formula.
+- Read the equation back in plain English. Right after a .. math:: block, add a sentence translating it ("which reads: distance to one sensor minus distance to the other equals...").
+- Explain why, not just what. For each fact, give the intuition behind it (why a range difference can't exceed the baseline) rather than stating it as a rule.
+- Define jargon inline the moment it appears ("the baseline," "ill-conditioned, meaning small errors move the estimate a lot") instead of assuming the reader knows it.
+- Use second person and rhetorical questions to walk the reader through the reasoning as if thinking aloud.
+
+## Notes
+
+- This project uses Sphinx and a custom `conf.py`.
+- The repository already contains scripts and generated assets for many figures, so prefer reusing existing conventions instead of introducing new build patterns.

CLAUDE.md

@@ -0,0 +1 @@
+AGENTS.md

Makefile

@@ -16,7 +16,7 @@ endif
 PAPEROPT_a4     = -D latex_paper_size=a4
 PAPEROPT_letter = -D latex_paper_size=letter
 ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
-EXTENSIONS      = -D extensions=sphinx.ext.mathjax,sphinx.ext.autosectionlabel,sphinxcontrib.tikz -D tikz_includegraphics_path=_images -D tikz_tikzlibraries=positioning,shapes,arrows,snakes
+EXTENSIONS      = -D extensions=sphinx.ext.mathjax,sphinx.ext.autosectionlabel,sphinxcontrib.tikz,sphinxcontrib.mermaid -D tikz_includegraphics_path=_images -D tikz_tikzlibraries=positioning,shapes,arrows,snakes
 # the i18n builder cannot share the environment and doctrees with the others
 I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
 

README.md

@@ -1,13 +1,13 @@
-# PySDR Textbook Source Material
-
-This repo contains the source content used to generate the textbook [PySDR: A Guide to SDR and DSP using Python](https://pysdr.org) hosted at https://pysdr.org.
-
-Feel free to submit an issue, or even a Pull Request (PR) with fixes or improvements.  Those who submit valuable feedback/fixes be permanently added to the acknowledgments section.  Not good at Git but have changes to suggest?  Feel free to email Marc at marc@pysdr.org.
+# PySDR
 
 <p align="center">
   <img width="200" src="https://raw.githubusercontent.com/777arc/PySDR/master/_images/fft_logo_wide.gif" />
 </p>
 
+[PySDR: A Guide to SDR and DSP using Python](https://pysdr.org) is a guide to software-defined radio (SDR) and RF signal processing using Python code examples, live at https://pysdr.org.  It is a free online textbook that provides a gentle introduction to wireless communications and SDR using an abundance of diagrams, animations, and code examples. From FFTs to filters to digital modulation to receiving and transmitting from SDRs in Python, PySDR has you covered!  This repo specifically contains the source content used to generate the textbook, including the body text and Python scripts to generate the figures.  For questions/comments/suggestions feel free to submit an issue at the top of this page, or if you want to propose a change to the textbook (e.g. fix or improvement), you can use a Pull Request.  Those who submit valuable feedback/fixes be permanently added to the acknowledgments section.  Not good at Git but have changes to suggest?  Feel free to email Marc at marc@pysdr.org.
+
+You can also support PySDR through the [PySDR Patreon page](https://www.patreon.com/c/PySDR) or a [one-time donation](https://www.paypal.com/donate/?hosted_button_id=FH3LQCJRUVPWL).
+
 ## Building
 
 Note that the website is now automatically built and deployed with each push/merge into master branch, using the GitHub action [build-and-deploy.yml](https://github.com/777arc/PySDR/blob/master/.github/workflows/build-and-deploy.yml) and the GitHub pages system for hosting the actual textbook.