docs: import old Python docs as Astro tutorials + executed notebooks

.github/workflows/docs.yml

@@ -23,10 +23,12 @@ on:
   pull_request:
     types: [opened, synchronize, reopened]
     paths:
-      # Site sources. Other paths (crates/, ppvm-python/) don't affect
-      # the build because the API JSON consumed by /api/ is committed
-      # under docs/src/data/ and regenerated manually.
+      # Site sources, the Rust workspace (consumed by the API JSON
+      # extractor), and the Python package (consumed by the notebook
+      # build step + the Python API extractor).
       - "docs/**"
+      - "crates/**"
+      - "ppvm-python/**"
       - ".github/workflows/docs.yml"
   pull_request_target:
     types: [closed]
@@ -83,24 +85,32 @@ jobs:
             echo "base=/" >> "$GITHUB_OUTPUT"
           fi
 
-      - name: Generate API JSON
-        # The /api/ page reads docs/src/data/{rust,python}-api.json,
-        # which are .gitignore'd and produced by docs/scripts/. The
-        # Rust extractor needs nightly for `--output-format json`;
-        # the Python extractor uses griffe via `uv run --with griffe`.
-        working-directory: docs
-        env:
-          RUSTFLAGS: "-C target-feature=+aes,+sse2"
+      - name: Compute git ref for source links
+        id: compute-ref
+        # "Source" links on the Examples pages resolve against this ref.
+        # PR previews use the PR head SHA so new files (that aren't on
+        # main yet) still link correctly; main deploys use the merge
+        # commit SHA so the link is stable forever.
         run: |
-          node scripts/extract-rust.mjs
-          node scripts/extract-python.mjs
+          if [[ "${{ github.event_name }}" == "pull_request" ]]; then
+            echo "ref=${{ github.event.pull_request.head.sha }}" >> "$GITHUB_OUTPUT"
+          else
+            echo "ref=${{ github.sha }}" >> "$GITHUB_OUTPUT"
+          fi
 
       - name: Build site
+        # `npm run build` aggregates the three extraction steps
+        # (`extract:rust`, `extract:python`, `extract:notebooks`) plus
+        # `astro build` into a single command. See `docs/README.md`
+        # for the per-step breakdown and the per-component escape
+        # hatches a developer would use locally.
         working-directory: docs
         env:
           PPVM_SITE: https://congenial-bassoon-l436wp3.pages.github.io
           PPVM_BASE: ${{ steps.compute-base.outputs.base }}
-        run: npx astro build
+          PPVM_GIT_REF: ${{ steps.compute-ref.outputs.ref }}
+          RUSTFLAGS: "-C target-feature=+aes,+sse2"
+        run: npm run build
 
       - name: Upload built site
         uses: actions/upload-artifact@v4

AGENTS.md

@@ -1,14 +1,17 @@
 # AGENTS.md
 
 > **Read the Developer Guide first.** The canonical contributor reference for
-> this repository — for both human and AI contributors — lives in the docs
-> site at `docs/src/pages/develop.astro` (rendered at `/develop/`). It covers
-> project layout, build/test commands, architecture, conventions, the Python
-> binding pipeline, and where to look for each subsystem.
+> this repository — for both human and AI contributors — is the Astro page
+> at [`docs/src/pages/develop.astro`](docs/src/pages/develop.astro) (rendered
+> at `/develop/` on the live site). It covers project layout, build/test
+> commands for the Rust workspace, the Python package, **and the docs site
+> itself** (`§ 2 Build & test`), architecture, conventions, the Python
+> binding pipeline, extension recipes, and the file-by-file "where to look
+> for X" table.
 >
-> This file is a short pointer so agents can find that guide quickly. Do not
-> add content here that belongs in the Developer Guide — keep the guide as
-> the single source of truth.
+> This file is a short pointer so agents can find that guide quickly. Do
+> not add content here that belongs in the Developer Guide — keep the
+> guide as the single source of truth.
 
 ## Install the ppvm-usage skill
 
@@ -29,13 +32,19 @@ internals.
 
 If you are an AI agent picking up a task in this repository:
 
-1. Open `docs/src/pages/develop.astro` and read the sections relevant to your
-   task. The "For AI agents" callout at the top tells you which sections are
-   load-bearing.
+1. Open [`docs/src/pages/develop.astro`](docs/src/pages/develop.astro) and
+   read the sections relevant to your task. The "For AI agents" callout at
+   the top tells you which sections are load-bearing.
 2. Use `uv` for anything Python; never `pip`.
 3. Use Conventional Commits: `<type>(<scope>): <description>`.
-4. Build & test with the commands documented in the guide
-   (`cargo test --workspace`, `uv run --project ppvm-python --group dev pytest …`).
+4. Build & test the relevant target:
+   - **Rust workspace**: `cargo test --workspace`
+   - **Python package**: `uv run --project ppvm-python --group dev pytest …`
+   - **Docs site**: `cd docs && npm run build` (chains `extract:rust`,
+     `extract:python`, `extract:notebooks`, then `astro build`).
+     Per-step commands and the `astro:dev` / `astro:build` escape
+     hatches are documented under `§ 2 → "This docs site"` in the
+     Developer Guide and in [`docs/README.md`](docs/README.md).
 5. Respect the `Config`-trait generics in `ppvm-runtime`; do not introduce
    runtime dispatch where a compile-time bound suffices.
 6. Pauli propagation runs **backwards** (Heisenberg picture). Reverse the

docs/.gitignore

@@ -3,3 +3,7 @@ dist/
 .astro/
 src/data/rust-api.json
 src/data/python-api.json
+# Outputs from `docs/scripts/build-notebooks.py`. The Jupytext sources
+# under `docs/notebooks/` are tracked; the executed HTML fragments,
+# their metadata, and the index are regenerated on every build.
+src/generated/

docs/README.md

@@ -0,0 +1,74 @@
+# ppvm docs site
+
+Astro site for the ppvm documentation. Deployed to gh-pages root by
+`.github/workflows/docs.yml`; PRs that touch this directory get a
+per-PR preview deploy.
+
+## Quick reference
+
+From this directory:
+
+```bash
+npm install                 # one-time
+npm run dev                 # extract + astro dev → http://127.0.0.1:4321
+npm run build               # extract + astro build → ./dist/
+```
+
+`npm run dev` and `npm run build` run every prerequisite extraction
+step first, so a fresh clone has one command to remember. Each
+extraction step is also available on its own when you're iterating on
+a specific layer:
+
+| Command                       | What it does |
+|-------------------------------|-----|
+| `npm run extract:rust`        | Re-run `cargo +nightly rustdoc -- --output-format json` for the three Rust crates and reshape into `src/data/rust-api.json`. Source: `scripts/extract-rust.mjs`. |
+| `npm run extract:python`      | Re-run `griffe dump ppvm` and reshape into `src/data/python-api.json`. Source: `scripts/extract-python.mjs`. |
+| `npm run extract:notebooks`   | Execute every Jupytext `.py` under `notebooks/` and emit HTML fragments + metadata to `src/generated/notebooks/`. Source: `scripts/build-notebooks.py`. |
+| `npm run extract`             | All three of the above, in order. |
+| `npm run astro:dev`           | `astro dev` without extracting anything — handy when you're editing only the Astro layer and trust the existing inputs. |
+| `npm run astro:build`         | `astro build` without extracting anything. |
+
+## Workflow patterns
+
+- **First clone / fresh checkout:** `npm install && npm run dev`.
+- **Iterating on the homepage / layout:** keep `npm run astro:dev` running; re-run `npm run extract:*` only when you change the underlying source.
+- **Changed a Rust public API:** `npm run extract:rust` then refresh the browser. The site picks up the regenerated `src/data/rust-api.json` automatically.
+- **Edited a notebook under `notebooks/`:** `npm run extract:notebooks`.
+- **Added a *new* notebook:** drop it into `notebooks/<name>.py` as a Jupytext-percent file, then `npm run extract:notebooks`. The Examples landing page picks it up from the regenerated `src/generated/notebooks/index.json`.
+
+## Layout
+
+```
+docs/
+├── notebooks/                       # Jupytext .py — executed at build time
+├── scripts/
+│   ├── extract-rust.mjs
+│   ├── extract-python.mjs
+│   └── build-notebooks.py
+├── src/
+│   ├── data/                        # *.json from extract:rust / extract:python  (gitignored)
+│   ├── generated/                   # notebooks/*.html + meta + index           (gitignored)
+│   ├── components/, layouts/, pages/, styles/
+│   └── ...
+├── package.json
+└── astro.config.mjs
+```
+
+`src/data/` and `src/generated/` are `.gitignore`'d; they're rebuilt on
+every CI run via `npm run extract`.
+
+## CI
+
+`.github/workflows/docs.yml` builds the site via `npm run build` on
+every PR that touches `docs/`, `crates/`, `ppvm-python/`, or itself.
+PR previews land at `gh-pages/pr-preview/pr-<N>/`; the main deploy
+publishes to `gh-pages` root on every push to `main`.
+
+## Prerequisites
+
+- Node ≥ 20 (Astro 5 requirement).
+- `uv` (https://docs.astral.sh/uv/) — used to drive the Python
+  notebook executor and the griffe-based Python extractor.
+- Rust nightly — `extract-rust.mjs` invokes `cargo +nightly rustdoc
+  --output-format json`. Install with `rustup toolchain install
+  nightly`.

docs/notebooks/msd.py

@@ -0,0 +1,144 @@
+# ---
+# jupyter:
+#   jupytext:
+#     cell_metadata_filter: -all
+#     custom_cell_magics: kql
+#     text_representation:
+#       extension: .py
+#       format_name: percent
+#       format_version: '1.3'
+#       jupytext_version: 1.19.1
+#   kernelspec:
+#     display_name: ppvm (3.12.12)
+#     language: python
+#     name: python3
+# ---
+
+# %% [markdown]
+# # Magic State Distillation with the Generalized Stabilizer Tableau
+#
+# Here we simulate an 85-qubit MSD circuit (5 code blocks of 17 qubits each) using ppvm's
+# `GeneralizedTableau`. It is loosely based on [the TSIM example](https://bloqade.quera.com/latest/digital/examples/tsim/magic_state_distillation/),
+# but with fewer details.
+
+# %%
+import time
+
+from ppvm import GeneralizedTableau, MeasurementResult
+
+QUBITS_PER_CODE_BLOCK = 17
+
+
+def encode(tab: GeneralizedTableau, qubits: list[int]) -> None:
+    """Apply the 17-qubit surface code encoding circuit."""
+    for i in [0, 1, 2, 3, 4, 5, 6, 8, 9, 10, 11, 12, 13, 14, 15, 16]:
+        tab.sqrt_y(qubits[i])
+
+    for i, j in [[1, 3], [7, 10], [12, 14], [13, 16]]:
+        tab.cz(qubits[i], qubits[j])
+    for i in [7, 16]:
+        tab.sqrt_y_adj(qubits[i])
+    for i, j in [[4, 7], [8, 10], [11, 14], [15, 16]]:
+        tab.cz(qubits[i], qubits[j])
+    for i in [4, 10, 14, 16]:
+        tab.sqrt_y_adj(qubits[i])
+    for i, j in [[2, 4], [6, 8], [7, 9], [10, 13], [14, 16]]:
+        tab.cz(qubits[i], qubits[j])
+    for i in [3, 6, 9, 10, 12, 13]:
+        tab.sqrt_y(qubits[i])
+    for i, j in [[0, 2], [3, 6], [5, 8], [10, 12], [11, 13]]:
+        tab.cz(qubits[i], qubits[j])
+    for i in [1, 2, 3, 4, 6, 7, 8, 9, 11, 12, 14]:
+        tab.sqrt_y(qubits[i])
+    for i, j in [[0, 1], [2, 3], [4, 5], [6, 7], [8, 9], [12, 15]]:
+        tab.cz(qubits[i], qubits[j])
+    for i in [0, 2, 5, 6, 8, 10, 12]:
+        tab.sqrt_y_adj(qubits[i])
+
+
+def msd_circuit(tab: GeneralizedTableau) -> list[MeasurementResult]:
+    """Build and measure the full 85-qubit MSD circuit."""
+    n_qubits = QUBITS_PER_CODE_BLOCK * 5
+    qubit_addrs = list(range(n_qubits))
+
+    # Split into 5 code blocks
+    ql = [
+        qubit_addrs[i * QUBITS_PER_CODE_BLOCK : (i + 1) * QUBITS_PER_CODE_BLOCK]
+        for i in range(5)
+    ]
+
+    # Prepare magic state in each block: H + T on encoding qubit, then encode
+    for q in ql:
+        encoding_qubit = q[7]
+        tab.h(encoding_qubit)
+        tab.t(encoding_qubit)
+        encode(tab, q)
+
+    # Cross-block entangling operations
+    for i in [0, 1, 4]:
+        for q in ql[i]:
+            tab.sqrt_x(q)
+
+    for control, target in zip(ql[0], ql[1]):
+        tab.cz(control, target)
+    for control, target in zip(ql[2], ql[3]):
+        tab.cz(control, target)
+
+    for q in ql[0]:
+        tab.sqrt_y(q)
+    for q in ql[3]:
+        tab.sqrt_y(q)
+
+    for control, target in zip(ql[0], ql[2]):
+        tab.cz(control, target)
+    for control, target in zip(ql[3], ql[4]):
+        tab.cz(control, target)
+
+    for q in ql[0]:
+        tab.sqrt_x_adj(q)
+
+    for control, target in zip(ql[0], ql[4]):
+        tab.cz(control, target)
+    for control, target in zip(ql[1], ql[3]):
+        tab.cz(control, target)
+
+    for i in range(5):
+        for q in ql[i]:
+            tab.sqrt_x_adj(q)
+
+    # Measure all qubits
+    return [tab.measure(i) for i in range(n_qubits)]
+
+
+# %% [markdown]
+# ## Running the circuit
+#
+# Each shot requires its own copy of the initial tableau since measurement mutates the state.
+# We use `fork()` to create independent copies with separate RNG streams.
+
+# %%
+n_qubits = QUBITS_PER_CODE_BLOCK * 5
+n_shots = 1000
+
+tab = GeneralizedTableau(n_qubits)
+
+start = time.perf_counter()
+
+results = []
+for shot in range(n_shots):
+    tab_shot = tab.fork(seed=shot)
+    results.append(msd_circuit(tab_shot))
+
+elapsed = time.perf_counter() - start
+
+print(f"Simulated {n_shots} shots of the {n_qubits}-qubit MSD circuit")
+print(f"Total time: {elapsed:.2f} s ({elapsed / n_shots * 1e3:.2f} ms per shot)")
+
+# %% [markdown]
+# Let's look at the measurement outcomes.
+
+# %%
+bitstrings = [
+    "".join("1" if r == MeasurementResult.ONE else "0" for r in shot)
+    for shot in results
+]