docs: check MSP references are up to date in CI

[bkleiner]

Adds a CI check that regenerates MSP docs and fails if they’re stale, similar to the existing Settings.md check. Updates regeneration instructions.

[qodo-code-review]

ⓘ Qodo reviews are paused because the subscription is no longer active. Ask your workspace admin to reactivate the subscription to resume reviews. Manage billing

[qodo-free-for-open-source-projects]

PR Summary by Qodo

Validate generated MSP references in documentation CI

✨ Enhancement ⚙️ Configuration changes 📝 Documentation 🕐 10-20 Minutes

AI Description

• Regenerates MSP references in CI and fails when checked-in outputs are stale.
• Runs documentation checks for MSP source, version, script, and output changes.
• Documents the expanded workflow triggers and required local regeneration command.

Diagram

graph TD
  A["Relevant changes"] --> B["Documentation workflow"] --> C["MSP docs job"] --> D["gen_docs.sh"] --> E["Generated references"] --> F{"Clean diff?"}
  F -- "Yes" --> G["CI passes"]
  F -- "No" --> H["CI fails"]

Loading

High-Level Assessment

Extending the existing documentation workflow is the best fit because MSP references are generated documentation and can follow the established regenerate-and-diff pattern used for Settings.md. A separate workflow would duplicate triggers and maintenance without improving isolation materially.

Files changed (3) +32 / -3

Documentation (2) +3 / -3

README.mdDocument expanded documentation CI coverage +2/-2

Document expanded documentation CI coverage

• Updates the workflow catalog to describe the broader documentation triggers and the stale-file checks for both settings and MSP references.

.github/workflows/README.md

Development.mdMark MSP document regeneration as CI-enforced +1/-1

Mark MSP document regeneration as CI-enforced

• Updates contributor guidance with the complete MSP generation inputs, all generated outputs, the local regeneration command, and the new CI enforcement behavior.

docs/development/Development.md

Other (1) +29 / -0

docs.ymlAdd CI validation for generated MSP references +29/-0

Add CI validation for generated MSP references

• Expands pull request and push path filters to include MSP generation inputs, outputs, firmware sources, and workflow changes. Adds a Python-enabled job that runs gen_docs.sh and fails with remediation instructions when generated MSP references differ from checked-in files.

.github/workflows/docs.yml

[qodo-free-for-open-source-projects]

Code Review by Qodo

🐞 Bugs (0) 📘 Rule violations (0) 📎 Requirement gaps (0) 🎨 UX issues (0) 🔗 Cross-repo conflicts (0) 📜 Skill insights (0)

1. Deleted MSP references pass CI ✓ Resolved 🐞 Bug ≡ Correctness

Description

The msp_docs job validates generated outputs with git diff, which ignores untracked files. If a
generated reference is deleted in the proposed commit, its generator recreates it as an untracked
file and the check succeeds, allowing the deletion to merge despite the documented CI guarantee.

Code

.github/workflows/docs.yml[53]

+          if ! git diff --exit-code -- README.md inav_enums.json inav_enums_ref.md; then

Evidence

The workflow checks only git diff after regeneration, while the generators create README.md,
inav_enums.json, and inav_enums_ref.md directly. The new development documentation explicitly
claims CI enforces all three outputs, so deleting one demonstrates a concrete gap in that guarantee.

.github/workflows/docs.yml[49-56]
docs/development/msp/gen_msp_md.py[428-438]
docs/development/msp/gen_enum_md.py[351-355]
docs/development/msp/gen_enum_md.py[367-383]
docs/development/Development.md[168-171]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The MSP documentation check uses `git diff`, so a generated file deleted by the commit can be recreated as an untracked file and remain invisible to CI.
## Issue Context
All three generators write their output paths anew. Validate repository status for the scoped outputs rather than only tracked-file diffs, while retaining a useful diff in failure logs.
## Fix Focus Areas
- .github/workflows/docs.yml[49-56]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

Tip of the day

💡 Did you know, you can tweak Display preferences with a live preview to see your comment before it ships

More tips ↗ | Customize Qodo ↗ | Qodo docs ↗

[github-actions]

RAM / Flash usage vs. base commit 768f381 — commit 7bc9db7

Target	Flash Δ	RAM Δ
MATEKF405	±0 B (±0.00%)	±0 B (±0.00%)
MATEKF722	±0 B (±0.00%)	±0 B (±0.00%)
MATEKF765	±0 B (±0.00%)	±0 B (±0.00%)
MATEKH743	±0 B (±0.00%)	±0 B (±0.00%)

See RAM/flash optimization guide for techniques to reduce usage.

[github-actions]

Test firmware build ready — commit 7bc9db7

Download firmware for PR #11875

249 targets built. Find your board's .hex file by name on that page (e.g. MATEKF405SE.hex). Files are individually downloadable — no GitHub login required.

Development build for testing only. Use Full Chip Erase when flashing.

[sensei-hacker]

Backported this PR's three commits onto release/9.1 (this PR targets maintenance-10.x) so the CI improvement lands earlier and flows forward naturally: #11946

On the Qodo finding flagged here (.github/workflows/docs.yml lines 49-56, "git diff ignores untracked files, so a deleted generated reference recreated as untracked would pass CI"): that describes the original git diff --exit-code approach's blind spot, which this PR's own third commit (7bc9db7) already fixes by switching to git status --porcelain — Qodo's own review marks it Resolved.

I sanity-checked that fix empirically while working on the backport: reproduced the exact scenario (delete a tracked generated file, let the generator recreate it without git add), and confirmed git status --porcelain -- <the 3 scoped paths> correctly reports it (D + ?? for the same path), while git diff --exit-code on the same scenario silently passes. So the fix here is correct and the finding is properly resolved — no further action needed on this PR for it.