Interactive playground¶

Local development only

Live code talks to a Jupyter server on your machine. It does not run on the static docs site or in CI.

On any page with Python or shell examples, use the icon buttons on the top-right of each block: edit, run, reset, copy. Edit opens a syntax-highlighted editor; run shows output below. Reset restores the original snippet.

Setup¶

Docs (from the repo root):

uv sync --extra dev
uv run mkdocs serve

While mkdocs serve is running, the header Live switch can start Jupyter for you if it is installed (uv sync --extra dev) but not running yet.

Optional — start Jupyter yourself in a second terminal:

./scripts/docs-jupyter.sh

Defaults: token retarget-docs, Jupyter at http://127.0.0.1:8888, docs at http://127.0.0.1:8000 (or http://localhost:8000 — both work). If MkDocs uses another host/port, set JUPYTER_ALLOW_ORIGIN_PAT when starting Jupyter.

Enable¶

Use the Live control in the top header (next to search): Inactive → flip the switch to Live (once per browser session). If Jupyter is not running, the status shows Not running — click the switch to start it (local mkdocs serve only) or run ./scripts/docs-jupyter.sh yourself.

Try it¶

from retarget import TaskKind

[task.value for task in TaskKind]

import numpy as np

np.linspace(0.0, 1.0, 5).tolist()

from pathlib import Path
import json

path = Path("tests/fixtures/minimal_motion.json")
motion = json.loads(path.read_text())
list(motion.keys())

Troubleshooting¶

Symptom	Fix
Run asks to turn on Live	Flip the switch so the status reads Live.
Status is Not running	With `mkdocs serve` running, click the switch to auto-start Jupyter. Or run `./scripts/docs-jupyter.sh` in another terminal, then click again.
Launcher 404 in MkDocs logs	Restart `mkdocs serve` once so the Jupyter helper loads (listens on `http://127.0.0.1:8889`). You should see `Live-code Jupyter launcher at http://127.0.0.1:8889/...` in the terminal.
Could not connect	Start Jupyter via `./scripts/docs-jupyter.sh`.
CORS errors / Not running	Restart Jupyter via `./scripts/docs-jupyter.sh` (allows both `localhost` and `127.0.0.1`). Open docs at the same host you used before, or set `JUPYTER_ALLOW_ORIGIN_PAT`.
Stuck on Connecting…	Hard-refresh the docs tab (`Cmd+Shift+R`). Stop Jupyter, run `pkill -f "ipykernel_launcher.*retarget"` to clear orphaned kernels, start `./scripts/docs-jupyter.sh` again, then toggle Live off and on.
Jupyter log spam (`Kernel does not exist` / channels 404)	Same as above — usually stale kernels from earlier failed connects.
`ModuleNotFoundError: retarget`	Run Jupyter with `uv run` from the repo root after `uv sync --extra dev`.

API reference signatures are not wired to the kernel. Elsewhere in the docs, hover a retarget symbol in a code block for its API tooltip, or click to jump to the definition.