94 lines
3.7 KiB
Markdown
94 lines
3.7 KiB
Markdown
|
---
|
||
|
|
model: claude-fable-5[1m]
|
||
|
|
service: claude
|
||
|
|
session: 0780a862-e19a-4f0a-86cd-c8afc0997757
|
||
|
|
timestamp: 2026-06-11T17:51:52Z
|
||
|
|
git_ref: 8526985c
|
||
|
|
scope: docs+code+config
|
||
|
|
substantive: true
|
||
|
|
raw_file: 20260611T175152Z_8526985c_prompt_io.raw.md
|
||
|
|
---
|
||
|
|
|
||
|
|
## Prompt
|
||
|
|
|
||
|
|
> we need big boi docs; ours are way out of date and generally
|
||
|
|
> terrible. i'd like to use a sphinx theme in the vein and/or
|
||
|
|
> one-of/nearly-the-same-as used in one or all of the `msgspec`,
|
||
|
|
> `numpy`, `ray`, `xonsh`, `polars` projects.
|
||
|
|
>
|
||
|
|
> see the following oustanding but now very old issues to guide
|
||
|
|
> you: #175, #126, #123, #157
|
||
|
|
>
|
||
|
|
> we should try to target a 3 columned sphinx theme with,
|
||
|
|
> - document index-nav on left,
|
||
|
|
> - body content in middle,
|
||
|
|
> - diagrams (ideally in d2lang if possible) on RHS
|
||
|
|
>
|
||
|
|
> optimize for (if possible),
|
||
|
|
> - reusing examples code without duplication in docs,
|
||
|
|
> - generating new examples from todos throughout code base,
|
||
|
|
> - distilling the essence of SC across processes in the simplest
|
||
|
|
> and most friendly way possible.
|
||
|
|
>
|
||
|
|
> do this work in a /open-wkt and do you best without my guidance
|
||
|
|
> for the first major pass - we will refine asap once you are
|
||
|
|
> complete.
|
||
|
|
|
||
|
|
Session settings: `/effort max` + ultracode (multi-agent workflow
|
||
|
|
orchestration). Fully autonomous first pass; two orchestrated
|
||
|
|
agent fleets were used (6-agent recon survey, then 10-agent
|
||
|
|
content fan-out: 9 section writers + 1 examples smith), with the
|
||
|
|
orchestrator authoring the landing page, SC essay, sphinx
|
||
|
|
scaffold, d2 pipeline + diagram sources, CI workflow and all
|
||
|
|
integration/fix passes directly.
|
||
|
|
|
||
|
|
## Response summary
|
||
|
|
|
||
|
|
Complete sphinx docs revamp on branch `wkt/big_boi_docs`:
|
||
|
|
`pydata-sphinx-theme` 0.18 (3-column: left nav / content /
|
||
|
|
page-toc, with d2 diagrams + asides floated into the RHS margin
|
||
|
|
via custom CSS), sphinx 9.1, a local `.. d2::` directive
|
||
|
|
rendering `docs/diagrams/*.d2` sources with committed-SVG
|
||
|
|
fallback, a vendored `.. margin::` directive, ~25 new doc pages
|
||
|
|
(landing, start/, explain/, 12 guides, 10 api-ref pages,
|
||
|
|
project/), 5 new auto-tested examples + 3 modernized + 1
|
||
|
|
renamed, and a gh-pages deploy workflow (issue #123). All
|
||
|
|
example code is `literalinclude`d from `examples/` (zero
|
||
|
|
duplication, CI-verified). Build: green, 24 warnings all
|
||
|
|
pre-existing-docstring/NEWS sourced.
|
||
|
|
|
||
|
|
## Files changed
|
||
|
|
|
||
|
|
See the branch diff (uncommitted at entry-write time):
|
||
|
|
|
||
|
|
> `git diff test_cpu_throttling..wkt/big_boi_docs`
|
||
|
|
> `git -C <wkt> status --short` (pre-commit working tree)
|
||
|
|
|
||
|
|
- `docs/conf.py` — full rewrite for pydata theme + ext stack
|
||
|
|
- `docs/_ext/d2diagrams.py` — new `.. d2::` sphinx directive
|
||
|
|
- `docs/_ext/marginalia.py` — new `.. margin::` directive
|
||
|
|
- `docs/_static/css/custom.css` — b&w skin + RHS margin floats
|
||
|
|
- `docs/diagrams/*.d2` (7) — diagram sources (sketch/grayscale)
|
||
|
|
- `docs/_diagrams/*.svg` (7) — committed rendered fallbacks
|
||
|
|
- `docs/index.rst` — new landing (replaces dead-API doc)
|
||
|
|
- `docs/start/*.rst` (3), `docs/explain/*.rst` (3),
|
||
|
|
`docs/guide/*.rst` (13), `docs/api/*.rst` (10),
|
||
|
|
`docs/project/*.rst` (3) — new content tree
|
||
|
|
- `docs/dev_tips.rst` — removed (ported to project/dev-tips)
|
||
|
|
- `examples/{typed_payloads,nested_actor_tree,
|
||
|
|
service_daemon_discovery,uds_transport_actor_tree,
|
||
|
|
streaming_broadcast_fanout}.py` — new, smoke-tested
|
||
|
|
- `examples/{a_trynamic_first_scene,
|
||
|
|
actor_spawning_and_causality,parallelism/single_func}.py` —
|
||
|
|
`.result()` -> `.wait_for_result()` modernization
|
||
|
|
- `examples/parallelism/concurrent_futures_primes.py` — renamed
|
||
|
|
from leading-underscore + trio-runner shim added
|
||
|
|
- `pyproject.toml` — `docs` dependency-group filled in
|
||
|
|
- `uv.lock` — relock for docs group
|
||
|
|
- `.github/workflows/docs.yml` — build + gh-pages deploy
|
||
|
|
|
||
|
|
## Human edits
|
||
|
|
|
||
|
|
None yet — entry written pre-commit; the author reviews, stages
|
||
|
|
and commits manually (per repo workflow policy).
|