From a75e8e08c26fcfd94ca9e0047809306a6c32a9ed Mon Sep 17 00:00:00 2001 From: goodboy Date: Fri, 26 Jun 2026 20:10:16 -0400 Subject: [PATCH] Document serving the docs over a LAN MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add a "Share on your LAN" blurb to both docs how-to homes (`notes_to_self/howtodocs.md` + the dev-tips "Building these docs" section): bind the server to all ifaces — via `sphinx-autobuild --host 0.0.0.0` (live-reload) or `python -m http.server --bind 0.0.0.0` (static) — so a peer on your subnet can hit `http://:8000` (`hostname -I` prints the ip). Verified a LAN-ip `curl` returns 200 + the socket binds `0.0.0.0`; includes a trusted-LAN-only caveat since it's an unauthenticated server on every interface. (this patch was generated in some part by [`claude-code`][claude-code-gh]) [claude-code-gh]: https://github.com/anthropics/claude-code --- docs/project/dev-tips.rst | 16 ++++++++++++++++ notes_to_self/howtodocs.md | 30 ++++++++++++++++++++++++++++++ 2 files changed, 46 insertions(+) diff --git a/docs/project/dev-tips.rst b/docs/project/dev-tips.rst index 528121a7..dff71745 100644 --- a/docs/project/dev-tips.rst +++ b/docs/project/dev-tips.rst @@ -156,6 +156,22 @@ every save:: --group docs sphinx-autobuild docs docs/_build/html # then open http://127.0.0.1:8000 +**Share on your LAN**: bind the server to all interfaces +(``--host 0.0.0.0``) instead of localhost, then hand a peer on +your subnet ``http://:8000``:: + + nix develop .#docs -c uv run --with sphinx-autobuild \ + --group docs sphinx-autobuild docs docs/_build/html \ + --host 0.0.0.0 --port 8000 + +or statically serve an already-built tree (no rebuild-on-save):: + + python -m http.server -d docs/_build/html --bind 0.0.0.0 8000 + +``hostname -I`` prints the IP to share; note it's an +unauthenticated server bound to every interface, so keep it to a +trusted LAN. + How the diagrams resolve, - ``.d2`` sources live in ``docs/diagrams/``; their rendered diff --git a/notes_to_self/howtodocs.md b/notes_to_self/howtodocs.md index d940a746..489d37b6 100644 --- a/notes_to_self/howtodocs.md +++ b/notes_to_self/howtodocs.md @@ -42,6 +42,36 @@ nix develop .#docs -c uv run --with sphinx-autobuild \ # then open http://127.0.0.1:8000 ``` +## Share it on your LAN + +To let someone on your subnet view the docs, bind the server to +all interfaces (`--host 0.0.0.0`) instead of just localhost, then +hand them `http://:8000`. + +Live-reload, LAN-visible: + +``` +nix develop .#docs -c uv run --with sphinx-autobuild --group docs \ + sphinx-autobuild docs docs/_build/html --host 0.0.0.0 --port 8000 +``` + +Or just statically serve an already-built `docs/_build/html` (no +rebuild-on-save): + +``` +python -m http.server -d docs/_build/html --bind 0.0.0.0 8000 +``` + +Find the IP to give them (first one is usually your LAN iface): + +``` +hostname -I +``` + +> Heads-up: this is an unauthenticated static server bound to +> every interface — fine on a trusted LAN, but don't leave it +> running on an untrusted/public network. + ## Diagrams (`d2`) - `.d2` sources live in `docs/diagrams/`; their rendered SVGs are