From c351671c1693df1cb7068c2f441d7824195c2590 Mon Sep 17 00:00:00 2001 From: goodboy Date: Thu, 25 Jun 2026 20:56:29 -0400 Subject: [PATCH] Document the docs build/preview flow Collect the sphinx build + live-preview one-liners (incl. the nix `.#docs` opt-in shell and the `d2` diagram specifics) so contributors don't have to reverse-engineer them, - new `notes_to_self/howtodocs.md` terse cheat-sheet (force-added past the `notes_to_self/` ignore, same as `howtorelease.md`), - a rendered "Building these docs" section in the dev-tips guide (`docs/project/dev-tips.rst`), - a README pointer to the note. (this patch was generated in some part by [`claude-code`][claude-code-gh]) [claude-code-gh]: https://github.com/anthropics/claude-code --- docs/README.rst | 5 +++ docs/project/dev-tips.rst | 59 +++++++++++++++++++++++++++++++++ notes_to_self/howtodocs.md | 67 ++++++++++++++++++++++++++++++++++++++ 3 files changed, 131 insertions(+) create mode 100644 notes_to_self/howtodocs.md diff --git a/docs/README.rst b/docs/README.rst index f68ebd9a..cd6b1211 100644 --- a/docs/README.rst +++ b/docs/README.rst @@ -110,6 +110,11 @@ Alongside all this we ofc offer "releases" on PyPi:: Just note that YMMV since the main git branch is often much further ahead then any latest release. +Hacking on the docs themselves? The build + live-preview one-liners +(incl. nix-shell specifics) are collected in `notes_to_self/howtodocs.md +`_, +and rendered as the "Building these docs" section of our dev-tips guide. + Example codez ------------- diff --git a/docs/project/dev-tips.rst b/docs/project/dev-tips.rst index 531a28fc..528121a7 100644 --- a/docs/project/dev-tips.rst +++ b/docs/project/dev-tips.rst @@ -121,6 +121,62 @@ Every record's header includes the emitting actor and task names, so cross-process flows can be stitched back together by eyeball (or grep). +Building these docs +------------------- +The site you're reading is sphinx_ + the pydata-sphinx-theme_, +with diagrams authored in d2_ (via our local ``.. d2::`` +directive) and *every* code block ``literalinclude``-d straight +from ``examples/`` — so what you read is what CI runs, and it +can't rot. + +The one-liner, from any dev shell:: + + uv run --group docs make -C docs html + +then open ``docs/_build/html/index.html``. + +**Nix users**: the d2_ 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 + +or as a one-shot without staying in the shell:: + + nix develop .#docs -c uv run --group docs make -C docs html + +**Live-reload** while editing — rebuild + browser refresh 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 + +How the diagrams resolve, + +- ``.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 + untouched). + +The build is currently **warning-free**; keep it that way — the +``-W`` flag turns any sphinx warning into a hard failure:: + + uv run --group docs sphinx-build -b html -W docs docs/_build/html + +A terser command cheat-sheet also lives at +``notes_to_self/howtodocs.md``. + .. seealso:: - :doc:`/guide/testing` — running the suite, watching trees live, examples-as-tests conventions and the zombie-reaper. @@ -131,3 +187,6 @@ so cross-process flows can be stitched back together by eyeball .. _uv: https://docs.astral.sh/uv/ .. _towncrier: https://towncrier.readthedocs.io/en/stable/ .. _stackscope: https://github.com/oremanj/stackscope +.. _sphinx: https://www.sphinx-doc.org/ +.. _pydata-sphinx-theme: https://pydata-sphinx-theme.readthedocs.io/ +.. _d2: https://d2lang.com diff --git a/notes_to_self/howtodocs.md b/notes_to_self/howtodocs.md new file mode 100644 index 00000000..d940a746 --- /dev/null +++ b/notes_to_self/howtodocs.md @@ -0,0 +1,67 @@ +# How to build + view the docs + +The site is `sphinx` + `pydata-sphinx-theme`, with diagrams in +[`d2`](https://d2lang.com) (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".