Collapse the deploy sub-pages back into one deploy.md (tabs, not separate
pages), add a working mermaid flow diagram, and rework the top per feedback.
- Mermaid: enable via superfences fence_div_format (the fence_code_format
<pre><code> wrapper broke mermaid's render — div format fixes it); vendor
mermaid.min.js locally (no CDN dependency for a self-hosted site) + a small
init that renders each block once and survives instant-nav.
- Content tabs Compose / Dockerfile / Secrets hold the three pieces together
on one page (inline comments in the code, no annotation +).
- 'What can run here' tip moved above the flow; section renamed
'Preparing for Deploy' with the 'you don't run deploy commands' point folded
sparsely into the intro (standalone note removed); 'svc never changes'
called out.
- Flow diagram (below the tabs): build group now includes our libraries; git
-> staging shown as develop-if-gitflow (dotted); deployment (no MR-to-main)
-> docker image built + run on the fleet.
- Revert inbound links to deploy.md.
Verified in-browser: diagram renders with all nodes, tabs switch, section
order correct; mkdocs build --strict clean.
Signed-off-by: disqualifier <dev@disqualifier.me>
The Deploy page got long and the code annotations rendered inconsistently
(some as (n) numbers, some as clickable +, and a marker on a fully-commented
line made that line vanish). Fix both:
- Deploy is now a HUB (docs/deploy/index.md): the intro + collision rule +
central-deploy note, then card links to three focused sub-pages. Deploy
stays the single global-nav entry; sub-pages are not_in_nav, reached from
the hub cards.
- deploy/compose.md — compose convention, storage tiers, how deploy fills
it in, subprocess/browser knobs, checklist
- deploy/dockerfile.md — services-account image, COPY, layer caching, uv
- deploy/secrets.md — keeping secrets out of the image
- Replace code annotations with INLINE COMMENTS on the compose/Dockerfile
examples: everything visible at once, no + to click, and the commented
MOUNTS_DIR line no longer disappears.
- Update inbound links (index card, standards, workflow, environments) to
deploy/ and deploy/compose.md; nav Deploy -> deploy/index.md with
not_in_nav for the sub-pages.
Verified in-browser: hub cards link correctly, sub-pages render with visible
inline comments (0 annotation markers), left nav shows only Deploy;
mkdocs build --strict clean (validates not_in_nav + all cross-links).
Signed-off-by: disqualifier <dev@disqualifier.me>
- deploy.md: new 'Getting your files into the image' subsection — a
multi-tab annotated block (single file / directory / deps-first) showing
COPY <src> <dest> patterns, plus a warning not to COPY secrets.
- clarify volume ownership: 'Logs and config are ours; the rest is yours' —
we inject/manage the logs + config host mounts; devs put everything else
in named volumes Docker owns.
- remove all /srv/mounts: dropped the MOUNTS_DIR volume + env var and every
mounts reference from the compose block, injected-vars, paths line, and
checklist. environments.md + index.md mounts mentions cleaned too.
Verified in-browser: COPY tabs switch, volume tip renders, zero mounts refs
remain; mkdocs build --strict clean.
Signed-off-by: disqualifier <dev@disqualifier.me>
uv is presented as the recommended faster, standards-compliant drop-in;
pip stays the baseline/fallback. uv command syntax verified against
docs.astral.sh/uv before writing.
environments.md:
- new 'uv (optional, faster)' section: install from pyproject
(uv pip install . / -e . / '.[dev]'), the uv sync managed-venv flow,
and a note that uv.lock is local-only/gitignored (not committed)
- pinning subsection: pin direct deps in pyproject via == or git @ref,
with a warning that this pins direct deps only — transitive deps still
float at build time (documented tradeoff)
- uv equivalents added beside pip in the Local .venv and Docker tabs
deploy.md:
- 'Faster builds with uv' tip: uv-from-ghcr COPY, ENV UV_COMPILE_BYTECODE=1,
uv pip install --system . (reads pyproject, no lock)
- layer-caching shows the uv variant beside the pip one
- checklist notes uv pip install + UV_COMPILE_BYTECODE; fix stray 'configs'
plural -> 'config'
.gitignore: ignore uv.lock (local-only, never committed).
Verified in-browser; mkdocs build --strict clean (anchors resolve).
Signed-off-by: disqualifier <dev@disqualifier.me>
New docs/environments.md, nav 'Virtual environments' (before Deploy):
- the rule: never touch system Python (danger callout)
- project-based isolation as Local .venv / Makefile-driven / Docker tabs,
each with a runnable snippet; Docker ties back to the deploy standard
- local dev with pyenv: why, official install link, shell init with
annotated lines, everyday use, per-project .python-version
- shell quality-of-life extras (flake8 alias, .local/bin + npm-global PATH),
cross-ref'd to Standards and Workflow
workflow.md pyenv bullet now points at the new page; index.md gains a card.
Verified in-browser: tabs switch (Local/Makefile/Docker), annotations and
admonitions render; mkdocs build --strict clean (cross-ref anchors resolve).
Signed-off-by: disqualifier <dev@disqualifier.me>
dsql