updated make docs

rig/.version

@@ -1 +1 @@
-0.1.1
+0.1.2

rig/ctrl/docs.sh

@@ -1,6 +1,8 @@
 #!/usr/bin/env bash
 # Documentation: render the diagrams, and serve the pages from a throwaway nginx container.
 # Usage: docs.sh serve | graphs
+# Whose: DOCS_DIR, the docs/ of the folder `make docs` runs from (a project's launcher sets
+# it); unset, rig's own.
 # Notes: docs/notes/docs.md
 set -euo pipefail
 cd "$(dirname "$0")"
@@ -9,11 +11,13 @@ source ./lib/config.sh
 load_config
 
 REPO="$(cd .. && pwd)"
+DOCS="${DOCS_DIR:-$REPO/docs}"
+[ -d "$DOCS" ] && DOCS="$(cd "$DOCS" && pwd)"
 DOCS_PORT="${DOCS_PORT:-$((HTTP_PORT + 4))}"   # +4 sits inside this env's block
 
 serve() {
-    if [ ! -f "$REPO/docs/index.html" ]; then
+    if [ ! -f "$DOCS/index.html" ]; then
-        echo "no docs/index.html" >&2
+        echo "no index.html in $DOCS" >&2
         exit 1
     fi
     # One worker and no access log: a few static pages need no more, and the
@@ -32,13 +36,14 @@ http {
 }
 NGINX
     chmod 644 "$DOCS_CONF"
-    echo "docs for '$CLUSTER' on http://localhost:${DOCS_PORT}"
+    echo "docs of $DOCS"
+    echo "  for '$CLUSTER' on http://localhost:${DOCS_PORT}"
     echo "  (ctrl-c to stop; nothing is installed and nothing persists)"
     docker run --rm \
         --name "${CLUSTER}-docs" \
         -e NGINX_ENTRYPOINT_QUIET_LOGS=1 \
         -p "${DOCS_PORT}:80" \
-        -v "$REPO/docs:/usr/share/nginx/html:ro" \
+        -v "$DOCS:/usr/share/nginx/html:ro" \
         -v "$DOCS_CONF:/etc/nginx/nginx.conf:ro" \
         nginx:alpine
 }
@@ -51,13 +56,13 @@ graphs() {
     fi
     shopt -s nullglob
     local found=0 f out
-    for f in "$REPO"/docs/graphs/*.dot; do
+    for f in "$DOCS"/graphs/*.dot; do
         out="${f%.dot}.svg"
         echo "  graphviz $(basename "$f") → $(basename "$out")"
         dot -Tsvg "$f" -o "$out"
         found=1
     done
-    [ "$found" -eq 1 ] || echo "  no .dot files in docs/graphs/"
+    [ "$found" -eq 1 ] || echo "  no .dot files in $DOCS/graphs/"
 }
 
 case "${1:-serve}" in

rig/ctrl/selftest.sh

@@ -193,6 +193,13 @@ check "the caller beats rig.env" "from-caller" \
 # Identity follows the overlay's folder, so one rig serves several without collisions.
 check "identity follows the overlay's folder" "my-env kind-my-env" \
     "$(in_ov env OVERLAY=local/My_Env bash ports.sh active | awk '{print $1, $2}')"
+mkdir -p "$OVR/local/renamed"; printf 'CLUSTER=pinned\n' > "$OVR/local/renamed/rig.env"
+check "rig.env's CLUSTER names it, whatever the folder" "pinned kind-pinned $(derive_port_base pinned)" \
+    "$(in_ov env OVERLAY=local/renamed bash ports.sh active | awk '{print $1, $2, $3}')"
+check "the caller's CLUSTER beats rig.env's" "second kind-second" \
+    "$(in_ov env OVERLAY=local/renamed CLUSTER=second bash ports.sh active | awk '{print $1, $2}')"
+check "make docs serves DOCS_DIR, the folder it runs from" "no index.html in $OVR/local/renamed" \
+    "$(in_ov env DOCS_DIR="$OVR/local/renamed" bash docs.sh serve 2>&1 >/dev/null | head -1)"
 check "paths in rig.env are relative to the overlay" "$OVR/local/My_Env/k8s/prod" \
     "$(in_ov env OVERLAY=local/My_Env bash ports.sh active | awk '{print $7}')"
 check "a named overlay that does not exist is an error" "yes" \

rig/docs/notes/docs.md

@@ -18,3 +18,12 @@ fails. The pages declare an empty icon, so the browser does not ask for a
 
 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.

rig/docs/notes/overlay.md

@@ -74,6 +74,36 @@ follow the overlay folder's name, sanitised the same way a rig folder's name is.
 One rig can therefore serve several overlays, each in its own cluster, and a
 project that carries rig at `./rig` does not name every cluster `rig`.
 
+That is the default. The convention is to pin the name in the overlay's `rig.env`:
+
+```
+CLUSTER=<name>
+```
+
+The name only has to be unique on the machine: the port block derives from it, so two
+overlays with the same name share one cluster and one set of ports. Pinned, it no longer
+follows the folder, so moving or renaming folders changes nothing. A second copy of the
+same project (another worktree, say) runs beside it by setting its own `CLUSTER=` in the
+project's ignored `.env.local`: the caller beats `rig.env`. Ports the workload forwards
+itself (a Tiltfile's `port_forwards`) are the overlay's, not the block's, and can still
+collide.
+
+A repository that runs on rig keeps it in a `devenv/` folder, with rig as the project's
+sibling:
+
+```
+devenv/
+  rig/              rig
+  <project>/        the forwarder (RIG_DIR ?= $(HERE)/../rig), its knobs, its data
+    overlay/        what rig reads
+```
+
+The overlay folder is then called `overlay/` in every project, so its name says nothing
+and `CLUSTER=` in its `rig.env` is required, not optional: left to the default, every such
+project would be the cluster `overlay`, on the same ports. The project folder, the cluster
+and the workload's namespace are three names: a folder may hold `_`, the other two are DNS
+labels.
+
 `ports.sh persist` refuses while an overlay is set: it writes to rig's
 `ctrl/.env`, and a pin there would follow every overlay.
 
@@ -164,6 +194,9 @@ RIG_DIR ?= $(HERE)/rig
 override RIG_DIR := $(abspath $(patsubst ~/%,$(HOME)/%,$(RIG_DIR)))
 ```
 
+`make docs` should serve the project's pages, not rig's: the forwarder names them with
+`DOCS_DIR := $(HERE)/docs` (see docs.md). rig's own stay `make -C <rig> docs`.
+
 No search path: an unset `RIG_DIR` means `./rig`, and nothing else is tried. Moving rig
 changes nothing in the cluster's name, context or ports; moving or renaming the overlay
 folder does.