tractor/.claude/ai_notes/docs_todos.md

Docs TODOs

Auto-sync README code examples with source

The docs/README.rst has inline code blocks that duplicate actual example files (e.g. examples/infected_asyncio_echo_server.py). Every time the public API changes we have to manually sync both.

Sphinx’s literalinclude directive can pull code directly from source files:

.. literalinclude:: ../examples/infected_asyncio_echo_server.py
   :language: python
   :caption: examples/infected_asyncio_echo_server.py

Or to include only a specific function/section:

.. literalinclude:: ../examples/infected_asyncio_echo_server.py
   :language: python
   :pyobject: aio_echo_server

This way the docs always reflect the actual code without manual syncing.

Considerations

• README.rst is also rendered on GitHub/PyPI which do NOT support literalinclude - so we’d need a build step or a separate _sphinx_readme.rst (which already exists at docs/github_readme/_sphinx_readme.rst).
• Could use a pre-commit hook or CI step to extract code from examples into the README for GitHub rendering.
• Another option: sphinx-autodoc style approach where docstrings from the actual module are pulled in.