not
17f1f2f809
## What & why `docs/` is the source of truth (CLAUDE.md §12), but only pages listed in `mkdocs.yml`'s nav are published — and mkdocs' own `validation.nav.omitted_files: warn` keeps the build green while dropping the rest. So the site had quietly stopped at **ADR-0010** and **`runbooks/ci.md`**: 31 pages, including every ADR from 0011 to 0034, six of the seven runbooks, and `synthetic-data.md`, existed in the repo and nowhere else. - `infra/check-docs-nav.py` fails when a page under `docs/` is not in the nav. It runs in `make lint`, so the existing CI job gates it — python3 only, no new tooling, and no mkdocs install needed to check it. - The nav now lists all 34 ADRs, all 7 runbooks and `synthetic-data.md`. - ADR-0033's `Slice:` header said "none yet"; #25 closed it. - The landing page gained a pointer to the Talos runbook. Closes #169 ## Definition of Done - [x] Linked Gitea issue (above). - [x] Failing test committed before the fix — the red commit lists all 31 missing pages. - [x] Implementation makes the test pass. - [x] Conventional Commits referencing the issue (`refs #169`). - [ ] CI green — awaiting the run on this PR (`python3 infra/check-docs-nav.py` passes locally; `make lint` also needs the .NET SDK, which CI has). - [x] `docker compose up` unaffected — docs and `mkdocs.yml` only, plus one `make lint` line. - [x] Docs updated — that is the change. - [x] No ADR needed: no dependency, no boundary, no §8 rule touched. - [x] Not user-visible, so no demo note. ## Notes for reviewers - The check is a **substring test**, not a YAML parse (there's a `ponytail:` note in the script): a page's path either appears in `mkdocs.yml` or it doesn't. That keeps it dependency-free — `mkdocs.yml` can't be read by `yaml.safe_load` anyway, it carries a `!!python/name:` tag for the mermaid fence. It does not check that an entry *points at a file that exists*; mkdocs' `not_found: warn` covers that direction. - ADR labels in the nav are shortened by hand (`"ADR-0013: Behandel-portal wiring"`), since several H1s are a full sentence. **Known gap, not fixed here:** CLAUDE.md §12 says the site is "published via a Gitea Actions workflow to Gitea Pages", and no such workflow exists — `mkdocs build` is never run, by CI or by any make target. Gitea has no built-in Pages, so publishing needs a decision (a `gitea-pages` server, an artifact, or a static host) rather than a patch. Worth its own issue if the published site is actually wanted; until then this PR makes the nav correct for whoever runs `mkdocs serve`.Reviewed-on: #172
31 lines
1007 B
Python
Executable File
31 lines
1007 B
Python
Executable File
#!/usr/bin/env python3
|
|
"""Fail when a page under docs/ is missing from mkdocs.yml's nav.
|
|
|
|
docs/ is the source of truth (CLAUDE.md §12), but only the pages listed in the nav
|
|
are published — and mkdocs' own `omitted_files: warn` keeps a build green while
|
|
silently dropping them, which is how every ADR after 0010 and every runbook but
|
|
ci.md fell off the site.
|
|
|
|
ponytail: a substring test, not a YAML parse — a page's path either appears in
|
|
mkdocs.yml or it doesn't, and that needs no dependency.
|
|
"""
|
|
|
|
import sys
|
|
from pathlib import Path
|
|
|
|
ROOT = Path(__file__).resolve().parents[1]
|
|
nav = (ROOT / "mkdocs.yml").read_text()
|
|
|
|
missing = sorted(
|
|
str(page.relative_to(ROOT / "docs"))
|
|
for page in (ROOT / "docs").rglob("*.md")
|
|
if str(page.relative_to(ROOT / "docs")) not in nav
|
|
)
|
|
|
|
if missing:
|
|
print(f"{len(missing)} page(s) under docs/ are not in mkdocs.yml's nav:")
|
|
print("\n".join(f" {m}" for m in missing))
|
|
sys.exit(1)
|
|
|
|
print("docs nav complete: every page under docs/ is published")
|