Docs (vibed) for serious: real documentation with a modern theme #460
Draft
goodboy wants to merge 9 commits into
Draft
Docs (vibed) for serious: real documentation with a modern theme #460goodboy wants to merge 9 commits into
goodboy wants to merge 9 commits into
Conversation
Swap the deprecated `portal.result()` calls for the modern `.wait_for_result()` spelling in, - `a_trynamic_first_scene.py` (x2) - `actor_spawning_and_causality.py` - `parallelism/single_func.py` These 3 are literalinclude'd by the new docs tree so the rendered code must teach the current api; the `debugging/` set still calls `.result()` (pexpect pattern-matched tests, left for a follow-up sweep). (this patch was generated in some part by [`claude-code`][claude-code-gh]) [claude-code-gh]: https://github.com/anthropics/claude-code
Rename `parallelism/_concurrent_futures_primes.py` -> `concurrent_futures_primes.py` so the example-runner (`test_docs_examples.py`) stops skipping it (leading `_` = excluded) and CI finally exercises the `concurrent.futures` baseline we compare against in the new parallelism guide. Deats, - keep the original executor code verbatim in a sync `check_primes()` fn for clean docs excerpting, - add module docstring + zero-arg `async def main()` + `trio.run(main)` guard per the runner conventions. (this patch was generated in some part by [`claude-code`][claude-code-gh]) [claude-code-gh]: https://github.com/anthropics/claude-code
New runnable (and so CI-auto-tested) scripts backing the new docs guides, each following the `test_docs_examples.py` runner conventions, - `typed_payloads.py`: `@tractor.context(pld_spec=)` typed `started()`/stream roundtrip + a deliberate `MsgTypeError` catch demoing send-side validation, - `nested_actor_tree.py`: 3-level tree w/ fan-out rpc through a mid-tier supervisor actor, - `service_daemon_discovery.py`: registered daemon located via `find_actor()`/`wait_for_actor()` sans any spawn-portal ref, - `uds_transport_actor_tree.py`: `enable_transports=['uds']` tree printing the filesystem sockaddr + kernel peer-pid creds, - `streaming_broadcast_fanout.py`: one ipc stream fanned out to N local tasks via `MsgStream.subscribe()`. All gaps were mined from in-code TODOs + the docs recon pass; see #175 for the orig tutorial wishlist. (this patch was generated in some part by [`claude-code`][claude-code-gh]) [claude-code-gh]: https://github.com/anthropics/claude-code
Fill in the long-TODO'd `[dependency-groups]` entry: `sphinx>=9.1` + `pydata-sphinx-theme>=0.18` + design/copybutton/opengraph/togglebutton exts; relock. Build via, `uv run --group docs make -C docs html` Theme choice per the #157 research: `numpy`, `ray` + `polars` all ride `pydata-sphinx-theme` these days (`ray` migrated off `sphinx-book-theme`, which now hard-pins a stale pydata 0.16.1 anyway). (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
7 hand-authored `docs/diagrams/*.d2` sources (sketch-mode, grayscale theme, `elk` layout) w/ their pre-rendered fallback SVGs committed under `docs/_diagrams/` (served as-is when no `d2` bin is found, eg. in CI), - `actor_tree`: the hero supervision-tree, - `context_handshake`: seq diagram of the `Start`/`StartAck`/`Started`/`Yield`/`Stop`/`Return` ctx dialog, - `streaming_pipeline`: 4-actor fan-in topology, - `runtime_stack`: the per-actor layer cake, - `debug_lock`: root-tty-lock REPL serialization, - `error_propagation`: one-cancels-all boxed-err flow, - `infected_aio`: guest-mode loop nesting. Rendered w/ `d2` v0.7.1 via `nix run nixpkgs#d2`. (this patch was generated in some part by [`claude-code`][claude-code-gh]) [claude-code-gh]: https://github.com/anthropics/claude-code
Replace the ancient `docs/index.rst` (still teaching `tractor.run()`, `@stream` + arbiters..) with a full ~32 page tree teaching ONLY the current api (`.wait_for_result()`, registrar naming, `@context` + `open_context()` as the core model), - landing: hero example, feature cards + canon links, - `start/`: install + a 4-example quickstart on-ramp, - `explain/`: an "SC across processes" essay distilling the essence per #157's orig ask + a runtime architecture tour, - `guide/`: 12 task-focused pages incl the flagship multi-process debugging walkthrough, `Context` + `MsgStream` deep-dives, cancellation semantics (self-vs-cross cancel rules), discovery, infected `asyncio`, typed msging + the #126 testing-tips page, - `api/`: 10 curated autodoc pages (all targets import-verified vs the reorg'd subpkg tree), - `project/`: changelog include, ported dev-tips (drops old `docs/dev_tips.rst`) + roadmap. Every code block is a `literalinclude` from `examples/` - zero duplication, all CI-run - w/ `d2` figs floated into the RHS margin per the 3-col design. Build is green; the 24 remaining warnings all source from lib docstring rst-isms or legacy `NEWS.rst` content. Substantially resolves #157 (refine round pending); chips at #175 + #126. Prompt-IO: ai/prompt-io/claude/20260611T175152Z_8526985c_prompt_io.md (this patch was generated in some part by [`claude-code`][claude-code-gh]) [claude-code-gh]: https://github.com/anthropics/claude-code
`docs.yml`: sphinx build on PRs + main pushes (via `uv sync
--no-dev --group docs`), deploying to gh-pages only from main
pushes using the official
`actions/{upload-pages-artifact,deploy-pages}` pair - the
`msgspec`-style flow wished for in #123. No `d2` bin in CI (yet) so
the committed SVGs serve as-is.
(this patch was generated in some part by [`claude-code`][claude-code-gh])
[claude-code-gh]: https://github.com/anthropics/claude-code
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
A first one-shot + soon-to-come refinements at up-to-date, beginner-friendly, intuitive & comprehensive
sphinxdocumentation 🏄🏼