tractor/docs/explain/index.rst

Big ideas
=========
The conceptual core of ``tractor``: what *structured
concurrency* (SC) means once your "tasks" are whole
processes, and how the runtime is layered to deliver
that without (much) magic.

If you only read one page in these docs make it
:doc:`sc-distributed`; if you read two, follow it with
:doc:`architecture`.

.. toctree::
   :maxdepth: 2

   sc-distributed
   architecture
Write the big boi docs content tree 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 2026-06-11 19:17:14 +00:00			`Big ideas`
			`=========`
			The conceptual core of ``tractor``: what *structured
			`concurrency* (SC) means once your "tasks" are whole`
			`processes, and how the runtime is layered to deliver`
			`that without (much) magic.`

			`If you only read one page in these docs make it`
			:doc:`sc-distributed`; if you read two, follow it with
			:doc:`architecture`.

			`.. toctree::`
			`:maxdepth: 2`

			`sc-distributed`
			`architecture`