From b444e0c6804ae0ef19c5f92c86e625859a9c0c8d Mon Sep 17 00:00:00 2001 From: Niek Otten Date: Mon, 28 Sep 2026 13:25:40 +0000 Subject: [PATCH] ci(docs): build the MkDocs site with --strict in CI (refs #173) (#189) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit refs #173. This is the minimum step from the issue: the site is now **built** in CI, not **published**. Publishing still needs an ADR (Gitea has no built-in Pages) or a CLAUDE.md ยง12 correction, so the issue stays open. - `make docs`: creates a throwaway `.venv-docs`, installs pinned `mkdocs==1.6.1` and `mkdocs-material==9.7.7`, then runs `mkdocs build --strict`. The target is also added to `make ci`. - New `docs` job in `ci.yaml` (`setup-python@v5`, then `make docs`). - Red, then green: the first commit fails on a link from `runbooks/ci.md` to a file outside `docs/`; the second turns that link into plain code. **Dependency (ยง13):** mkdocs and mkdocs-material were already the site's declared toolchain (`mkdocs.yml`) but were never installed anywhere. They give a strict link/nav/theme check. Replacing them means writing our own Markdown link checker, and `check-docs-nav.py` already covers only the nav half. Risk: Material warns that MkDocs 2.0 drops its plugin/theme system, so both are pinned exactly. No ADR, since this adds no new decision beyond what `mkdocs.yml` already assumes. Verified locally: `make docs` โ†’ `Documentation built in 0.87 seconds`. ๐Ÿค– Generated with [Claude Code](https://claude.com/claude-code)Reviewed-on: https://git.labs.respellion.tech/eho/register-referentie/pulls/189 --- .gitea/workflows/ci.yaml | 11 +++++++++++ .gitignore | 4 ++++ Makefile | 13 +++++++++++-- docs/runbooks/ci.md | 3 ++- 4 files changed, 28 insertions(+), 3 deletions(-) diff --git a/.gitea/workflows/ci.yaml b/.gitea/workflows/ci.yaml index f3a91fc..d8e13f8 100644 --- a/.gitea/workflows/ci.yaml +++ b/.gitea/workflows/ci.yaml @@ -98,6 +98,17 @@ jobs: [ -n "${GITHUB_STEP_SUMMARY:-}" ] || exit 0 python3 infra/trx-summary.py TestResults >> "$GITHUB_STEP_SUMMARY" + # The docs site must build with --strict (#173). setup-python so `make docs` can + # create its venv regardless of what the runner image ships. + docs: + runs-on: ubuntu-latest + steps: + - uses: https://github.com/actions/checkout@v4 + - uses: https://github.com/actions/setup-python@v5 + with: + python-version: '3.12' + - run: make docs + # Frontend (Nx/Angular) lane: install with pnpm, then Nx lint + test + build. frontend: runs-on: ubuntu-latest diff --git a/.gitignore b/.gitignore index b8d2203..cc50a76 100644 --- a/.gitignore +++ b/.gitignore @@ -61,3 +61,7 @@ __pycache__/ TestResults/ test-output/ tests/e2e/playwright-report.json + +# MkDocs build (`make docs`) +.venv-docs/ +site/ diff --git a/Makefile b/Makefile index 9c76f3b..c6d3828 100644 --- a/Makefile +++ b/Makefile @@ -43,11 +43,11 @@ export DOCKER_HOST := unix://$(PODMAN_SOCK) endif endif -.PHONY: ci lint build unit mutation frontend integration verify verify-up verify-acl verify-nrc verify-projection verify-bff verify-domain verify-observability verify-tracing verify-metrics verify-objecttypen verify-objecten verify-registerrecord verify-objecten-notifications verify-notifications smoke up down local verify-local local-down changelog openzaak-up openzaak-smoke openzaak-seed openzaak-down stack-up stack-smoke stack-down keycloak-up keycloak-smoke keycloak-down flowable-up flowable-smoke flowable-down k8s-lint k8s-drift k8s-registry k8s-images k8s-seed k8s-up k8s-reseed k8s-portals k8s-down k8s-purge help +.PHONY: ci lint build unit mutation frontend docs integration verify verify-up verify-acl verify-nrc verify-projection verify-bff verify-domain verify-observability verify-tracing verify-metrics verify-objecttypen verify-objecten verify-registerrecord verify-objecten-notifications verify-notifications smoke up down local verify-local local-down changelog openzaak-up openzaak-smoke openzaak-seed openzaak-down stack-up stack-smoke stack-down keycloak-up keycloak-smoke keycloak-down flowable-up flowable-smoke flowable-down k8s-lint k8s-drift k8s-registry k8s-images k8s-seed k8s-up k8s-reseed k8s-portals k8s-down k8s-purge help ## ci: run the full pipeline โ€” lint, build, unit, mutation, frontend, verify (mirrors Gitea Actions) ## `verify` is the live-stack stage (full stack up once โ†’ ACL + notification checks). -ci: lint build unit mutation frontend verify +ci: lint build unit mutation frontend docs verify ## frontend: install deps and run the Nx lint/test/build for the portals (pnpm + Node required) # Tests run in their own phase, ahead of the build. The @angular/build:unit-test @@ -81,6 +81,15 @@ unit: python3 infra/test_playwright_summary.py python3 infra/test_portal_caddyfiles.py +## docs: build the MkDocs site with --strict (a broken link or nav entry fails) +# Pinned in a throwaway venv: Material 9.7 is the last line on MkDocs 1.x, and MkDocs +# 2.0 drops the plugin/theme system this site relies on. Publishing is a separate +# decision (#173); this only proves the site builds. +docs: + python3 -m venv .venv-docs + .venv-docs/bin/pip install --quiet mkdocs==1.6.1 mkdocs-material==9.7.7 + .venv-docs/bin/mkdocs build --strict + ## mutation: run the Stryker.NET ratchet on each service with branching logic (fails below baseline) # Stryker is pinned as a local dotnet tool (.config/dotnet-tools.json); `tool restore` # makes `make mutation` work from a fresh clone. Each service owns its config + break diff --git a/docs/runbooks/ci.md b/docs/runbooks/ci.md index 26ded11..55ece68 100644 --- a/docs/runbooks/ci.md +++ b/docs/runbooks/ci.md @@ -19,6 +19,7 @@ and CI cannot drift: | `build` | `make build` โ†’ `dotnet build โ€ฆ -c Release` | .NET 10 SDK | | `unit` | `make unit` โ†’ `dotnet test โ€ฆ -c Release --filter "Category!=Integration"` | .NET 10 SDK | | `frontend` | `make frontend` โ†’ Nx lint/test/build for the four portals | pnpm + Node | +| `docs` | `make docs` โ†’ `mkdocs build --strict` in a pinned venv (fails on a broken link or nav entry; the site is not published yet, #173) | Python 3 | | `k8s` | `make k8s-lint` (render + schema-check the Helm chart) โ†’ `make k8s-drift` (chart still describes the same stack as `infra/docker-compose.yml`) | pinned `helm` binary + `docker compose` | | `mutation` | `make mutation` โ†’ `dotnet tool restore` โ†’ `dotnet stryker` (ACL); uploads the HTML report as an artifact | .NET 10 SDK | | `verify-stack` | **push to `main` only, skipped on PRs** (#182) โ€” the single live-stack stage โ€” steps: `make verify-up` (full stack up + health, the DoD smoke) โ†’ `make verify-acl` (ACL โ†” OpenZaak) โ†’ `make verify-nrc` (OpenZaak โ†’ NRC delivery) โ†’ `make down` | container engine + egress (base images, nuget, `selectielijst.openzaak.nl`) | @@ -57,7 +58,7 @@ dotnet tool (`.config/dotnet-tools.json`), so it runs identically locally and in make mutation # dotnet tool restore + dotnet stryker on the ACL ``` -Config lives in [`services/acl/stryker-config.json`](../../services/acl/stryker-config.json). +Config lives in `services/acl/stryker-config.json`. It runs in **solution mode** against `Acl.slnx`, mutating the two projects under test (`Acl.Application`, `Acl.Infrastructure`); `Acl.Api` has no tests and is skipped. `Acl.slnx` leaves out `Acl.IntegrationTests`: it needs a live OpenZaak, and Stryker