eSlider
e6e57843cb
CI & Release / Verify documentation (push) Skipped
CI & Release / Verify simulator (push) Skipped
CI & Release / Trivy scan (push) Skipped
CI & Release / Semantic Release (push) Skipped
CI & Release / Verify documentation (pull_request) Successful in 5s
CI & Release / Verify simulator (pull_request) Failing after 9s
CI & Release / Trivy scan (pull_request) Skipped
CI & Release / Semantic Release (pull_request) Skipped
Enforce link resolution, glossary anchors, and readability rules on every push and PR; docs-only pushes to main still run docs-verify while skipping the simulator gate.
2.4 KiB
2.4 KiB
CI documentation rules
Automated checks for markdown in this repository. Enforced on every pull request and on push to main (including docs-only pushes that skip the simulator gate).
Implementation: scripts/check_docs.py reads scripts/docs_rules.yaml.
Workflow: .github/workflows/release.yaml job Verify documentation.
Tracked from issue #1 and the 2026-07-10 audit.
Gates
| Rule | Severity | What it checks |
|---|---|---|
| Relative links | error | Every [text](path) and [text](path#anchor) to a local .md file resolves to an existing file |
| Fragment anchors | error | #anchor fragments match a ## or ### heading in the target file (GitHub-style slug) |
| Banned targets | error | Known-bad paths (e.g. deleted 03-storage-design.md) are not linked |
| Glossary fragments | error | All 00-glossary.md#… links use anchors that exist in the glossary |
| Section vs term links | warning | Links to glossary section headers (#swarm--robotics, …) are listed; prefer ### term anchors where they exist |
| Bare cross-refs | error | Prose cross-references to numbered docs without a proper markdown link |
Warnings are printed in the job log but do not fail CI. Errors exit non-zero and block merge.
PR workflow
flowchart LR
PR[Pull request] --> DV[docs-verify]
PR --> V[verify simulator]
V --> S[Trivy scan]
DV --> OK{All required green?}
V --> OK
S --> OK
OK -->|yes| Merge[Mergeable]
| Event | docs-verify |
verify + scan |
|---|---|---|
PR → main |
always | always |
Push → main (code paths) |
always | runs |
Push → main (docs/README/AGENTS only) |
always | skipped (paths-ignore) |
Docs-only changes therefore still get link and glossary validation on main; they do not trigger a semantic release.
Local run
python scripts/check_docs.py
python scripts/check_docs.py --warnings-as-errors # treat section-link warnings as failures
Changing rules
- Edit
scripts/docs_rules.yaml(paths, banned targets, preferred anchors). - Adjust
scripts/check_docs.pyonly when adding a new rule type. - Add a row to the table above and mention it in the audit/improvement record if the change is significant.