Document serving the docs over a LAN

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://<lan-ip>: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_vibed_for_serious
Gud Boi 2026-06-26 20:10:16 -04:00
parent c351671c16
commit 3072686c49
2 changed files with 46 additions and 0 deletions

View File

@ -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://<your-lan-ip>: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

View File

@ -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://<your-lan-ip>: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