docs(site): close the excluded-PRD link chain and reconcile the CI section
Two fixes to the published site, both about not shipping something false. exclude_docs held back prds/ but let ui-service-boundary.md through, because architecture/migration-decisions.md links to it three times. That PRD in turn links to service-decomposition.md and config-schema.md, so the exclusion was still producing two dead links on the published site. Letting those two through closes the chain: the build now reports no excluded-link references at all. generated-documentation.md's "Step 9: CI" said no workflow builds, checks or publishes documentation. Adding .github/workflows/docs.yml made the first clause false. Restated to say what that workflow does and, more importantly, what it deliberately does not: it does not run docsgen, regenerate contracts.json, or publish. Generated-artifact drift is still gated locally by task check, which is the split that section exists to protect, since a CI job that regenerated output could paper over uncommitted differences rather than fail on them.
This commit is contained in:
1 parent
8adc010577
commit
a533810546
2 files changed
+17
-6
No files matched your search
@@ -349,13 +349,22 @@ exist, and only the single `contracts.json` artifact is generated today.
|
||||
|
||||
### Step 9: CI
|
||||
|
||||
The documentation workflow was deleted on 2026-09-12. No workflow builds, checks,
|
||||
or publishes documentation. `deploy.yml` does not reference `docs/**`.
|
||||
The original documentation workflow was deleted on 2026-09-12. `deploy.yml` still
|
||||
does not reference `docs/**`.
|
||||
|
||||
Drift is therefore gated locally, by `task check` running `docs:check` — not in
|
||||
CI. Reintroducing CI for documentation requires the renderer decision first.
|
||||
Any such workflow MUST check generated output and MUST NOT regenerate and
|
||||
silently publish uncommitted differences.
|
||||
`.github/workflows/docs.yml` (added 2026-09-18) builds the MkDocs site with
|
||||
`mkdocs build --strict` on changes to `docs/**` or `mkdocs.yml`, so a dead
|
||||
internal link fails before it reaches a deploy. It deliberately does no more
|
||||
than that: it does not run `docsgen`, does not regenerate `contracts.json`, and
|
||||
does not publish. Deployment is a separate path, run from the Ansible control
|
||||
node by the `vectislabs.automation` `docs_site` role.
|
||||
|
||||
Generated-artifact drift is therefore still gated locally, by `task check`
|
||||
running `docs:check`, and not in CI. That split is the point. A CI job that
|
||||
regenerated output would be able to paper over uncommitted differences instead
|
||||
of failing on them, which is the failure this section exists to prevent, so any
|
||||
future documentation workflow MUST check generated output rather than produce
|
||||
it.
|
||||
|
||||
### Step 10: cutover — done, in reverse
|
||||
|
||||
|
||||
@@ -19,6 +19,8 @@ exclude_docs: |
|
||||
inspiration/
|
||||
prds/*
|
||||
!prds/ui-service-boundary.md
|
||||
!prds/service-decomposition.md
|
||||
!prds/config-schema.md
|
||||
github-token.md
|
||||
|
||||
theme:
|
||||
|
||||
Reference in new issue
Block a user