tractor/notes_to_self/howtodocs.md

How to build + view the docs

The site is sphinx + pydata-sphinx-theme, with diagrams in d2 (our local .. d2:: directive) and every code block literalinclude-d straight from examples/ (never copy-pasted — what you read is what CI runs).

TL;DR

uv run --group docs make -C docs html
firefox docs/_build/html/index.html

Nix users

d2 (the diagram renderer) is deliberately kept out of the default dev-shell so casual envs stay lean; it lives in an opt-in docs shell:

# enter the docs shell (puts `d2`, `uv` + python on PATH)
nix develop .#docs

# ...then build (diagrams re-render from docs/diagrams/*.d2)
uv run --group docs make -C docs html

one-shot, without staying in the shell:

nix develop .#docs -c uv run --group docs make -C docs html

Live-reload while editing

Rebuilds + refreshes the browser on every save:

nix develop .#docs -c uv run --with sphinx-autobuild \
    --group docs sphinx-autobuild docs docs/_build/html
# then open http://127.0.0.1:8000

Diagrams (d2)

• .d2 sources live in docs/diagrams/; their rendered SVGs are git-committed under docs/_diagrams/ as a fallback.
• with a d2 binary on PATH (the .#docs shell, or set D2_BIN='nix run nixpkgs#d2 --') any stale SVG re-renders at build time.
• with NO binary, the committed SVGs are served as-is, so CI and casual builds need no d2 at all.
• a .d2 that fails to compile is a hard build error under sphinx-build -W (the last-good committed SVG is left intact).

Keep it warning-free

The build is currently 0-warning — keep it that way. -W turns any sphinx warning into a failure:

uv run --group docs sphinx-build -b html -W docs docs/_build/html

The rendered version of this note lives in the contributor guide: docs/project/dev-tips.rst → “Building these docs”.