The `context_handshake` sequence diagram only showed the graceful
`Return` ending - underselling the whole SC pitch (errors + cancels
propagate *both* ways across the wire). Add a "... or, instead of a
graceful Return" group with the non-graceful endings,
- parent-initiated: `ctx.cancel()` (or a parent-side error) ->
child relays `Error: ContextCancelled`,
- child-initiated: child ships `Error: <raised>` (or
`ContextCancelled`).
Labelled `Error: ...` since `ContextCancelled` is an exception that
rides inside an `Error` wire msg, not its own msg type - keeping
the diagram's wire-level labels honest. Re-render the committed
`_diagrams/context_handshake.svg` fallback (CI has no `d2` bin) to
match.
Also cache-bust d2 images in `d2diagrams.py`: sphinx tags css/js
with `?v=<hash>` but not images, so an edited diagram kept serving
the browser's stale copy at the stable `_images/<stem>.svg` url
(cost us a manual hard-refresh). Hash each rendered svg + rewrite
only the d2 `<img src>` to `...svg?v=<hash8>` via the
`html-page-context` hook - content-addressed, so unchanged diagrams
keep their query.
(this patch was generated in some part by [`claude-code`][claude-code-gh])
[claude-code-gh]: https://github.com/anthropics/claude-code
Three robustness fixes surfaced by the PR #460 self-review,
- a render that's *attempted and fails* (a `d2` bin is present but
errors on the source) now raises a docutils error instead of
silently serving the stale committed SVG — so `sphinx-build -W`
fails on a broken `.d2` edit. The no-binary case stays a quiet
committed-SVG fallback.
- render into a sibling temp-file then `os.replace()` so a
failed/torn render can never clobber a good committed SVG.
- guard against 2 distinct `.d2` sources colliding on a single
`_diagrams/<stem>.svg` within a build.
`render_svg()` now returns a `RenderResult` tristate that `run()`
maps to error / raw-source-literal / image.
(this patch was generated in some part by [`claude-code`][claude-code-gh])
[claude-code-gh]: https://github.com/anthropics/claude-code
Full `docs/conf.py` rewrite targeting `pydata-sphinx-theme` 0.18
(3-col layout: nav-index left, content middle, page-toc right)
skinned to a minimal b&w look via `_static/css/custom.css`, keeping
the `algol_nu` pygments style.
Also add 2 local sphinx exts under `docs/_ext/`,
- `d2diagrams.py`: a `.. d2::` directive rendering `d2lang` sources
at build time when a `d2` bin is found (`D2_BIN` env supports
argful values eg. `'nix run nixpkgs#d2 --'`), falling back to any
git-committed SVG, else emitting the raw source as a literal
block; no pypi ext was usable (all stubs or returncode-swallowing
per the #157 research),
- `marginalia.py`: a theme-agnostic `.. margin::` directive
(`sphinx-book-theme` style `Sidebar` subclass) for prose-anchored
RHS asides; the custom css floats these (and `:margin:` d2 figs)
into the right gutter on wide screens.
(this patch was generated in some part by [`claude-code`][claude-code-gh])
[claude-code-gh]: https://github.com/anthropics/claude-code
Gud Boi