30 lines
1.4 KiB
Markdown
30 lines
1.4 KiB
Markdown
# ctrl/docs.sh
|
|
|
|
## Serving without the cluster or python
|
|
|
|
The docs are the instructions for building the cluster, so they must work before
|
|
anything else exists. That rules out serving them from the cluster, and it rules
|
|
out `python -m http.server` too — a minimal Debian has no python3. What it does
|
|
have, by definition, is Docker: the single prerequisite rig already demands. So a
|
|
throwaway nginx container serves a read-only bind mount.
|
|
|
|
It runs with a config of its own: one worker (nginx's `auto` starts one per core,
|
|
twelve on an ordinary laptop, for a handful of static pages), no access log and a
|
|
quiet entrypoint, so the terminal shows the URL and nothing else unless something
|
|
fails. The pages declare an empty icon, so the browser does not ask for a
|
|
`favicon.ico` that is not there.
|
|
|
|
## Committed SVGs
|
|
|
|
Rendered SVGs are committed alongside their `.dot` sources for the same reason:
|
|
the pages have to read on a machine with no Graphviz installed.
|
|
|
|
## Whose docs
|
|
|
|
`make docs` serves the docs of the folder it runs from. In rig that is rig's own `docs/`. A
|
|
project's launcher sets `DOCS_DIR` to its own `docs/` (an absolute path), so `make docs` there
|
|
serves the project's pages through this same script, on the same terms: an `index.html` at
|
|
the top, the environment's block for the port (`HTTP_PORT + 4`), a container named after the
|
|
environment. rig's own docs stay one `make -C <rig> docs` away. The project keeps no copy of
|
|
this script.
|