tractor/ai/prompt-io/claude/20260611T175152Z_8526985c_prompt_io.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 literalincluded 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).