fix(pipeline): migrate to nested topic URLs, fix page-path bugs, re-extract from real 2.12

[pfeerick]

Summary

The site's current flat URLs (api-reference/runtime-flush-audio/) leak an internal, non-Lua "runtime" grouping label and don't match either the official EdgeTX/lua-reference-guide's existing convention (lua-api-reference/system/rgb.md) or this pipeline's own page_name_for_item code, which was clearly written to produce nested topic URLs but never actually matched what's live -- build appears to have only ever targeted the isolated docs-system/generated/site-preview/ scratch directory, never website/md-docs/ itself, so the code and the live content silently drifted apart over time.

This PR fixes the pipeline properly and uses it to do a full, safe rebuild, landing three things together since they turned out to be entangled:

1. Page-path bugs fixed in tools/docs_pipeline.py (see inline commit message for full detail):

• group_page_name / module_page_name / review_page_name_for_item now match the flat scheme already live. Removed the now-redundant legacy_* variants.
• page_name_for_item moves individual item pages to nested api-reference/<topic-group>/<item>.md, dropping the internal-only "runtime" pseudo-module prefix from bare functions (kept for real namespaces: model., lcd., lvgl., Bitmap.).
• page_href (used for hub-page raw-HTML <a> card links, which MkDocs does not auto-correct the way it does markdown-syntax links) had a real bug: it didn't account for a flat page's own rendered URL being one directory level deeper than its file location under MkDocs' use_directory_urls default. Hand-verified against every from/to page-kind combination, then confirmed empirically against real built HTML.
• The review dashboard moved from a dead-end nested review/index.md to flat review.md, which also matters for correctness: mkdocs.yml's exclude_docs: api-reference/review.md pattern (from the earlier public/dev config split) wouldn't have matched the nested path, meaning the internal dashboard would have leaked into the public build.
• Found and fixed a real group-taxonomy drift in docs-system/api-groups.json while verifying the rebuild: a "hardware" slug that didn't match nav's "radio-hardware", and one merged "Variables" group still listing all 18 ids even though the live sources.md/switches.md/variables.md pages were already hand-split three ways (matching HANDOFF.md's "Sources, Switches, and Variables were separated properly"). Re-split the config to match, and wired the "Inputs" (key-inputs) group into nav -- it had a real 5-item group defined but no nav entry at all.

2. Re-extracted against the real 2.12 firmware branch (was extracted from a dev branch, cpm-tlm-sim-fix, even though this site targets 2.12 specifically): screenshot, model.getGlobalVariableDetails, model.setGlobalVariableDetails now correctly appear (they use @function style after EdgeTX/edgetx#7769 landed, previously silently dropped by the extractor); model.getSwitchWarning/setSwitchWarning are correctly absent (exist on main, not real 2.12 firmware -- the old baseline would have misrepresented them as 2.12 APIs). Deleted their now-orphaned pages explicitly, since build's stale-cleanup only knows about paths for items still present in the model, not items removed entirely.

3. Full content rebuild + link fixes: regenerated all api-reference pages/hub-cards/module-dashboards/review-pages from the fixed pipeline; fixed every inbound link across the site (6 narrative files under api-overview//programming/) that pointed at an individual function page by its old flat path; re-fixed a set of broken markdown links inside assets/luals/lcd.d.lua/runtime.d.lua that a prior pass (#2) had already fixed in generated output, but rebuilding from the still-unfixed raw upstream /*luadoc*/ comments silently regenerated the same breakage (documented in docs-system/REAL-EXTRACTION-NOTES.md as a recurring issue until a small upstream firmware PR fixes the actual comments, same pattern as #7769).

api-reference/lvgl-*.md (handled by the separate open PR #5) are untouched -- confirmed via git status.

Update: code review fixes

A review pass found two real regressions and two minor issues, all addressed in a follow-up commit:

1. Critical -- display-lvgl.md was silently clobbered. build_outputs() unconditionally regenerates every group's hub page from the model, including zero-item groups -- and "display-lvgl" has zero extracted items (LVGL firmware has no luadoc annotations at all), so the rebuild overwrote the hand-authored hub page with the generic empty-group stub. Fixed build_outputs so a zero-item group's existing real content is never overwritten or deleted by the stale-page cleanup pass (which ran before the per-group write loop and would unlink it regardless of any check placed after it -- had to move the check earlier). Verified only two groups currently have zero items (constants, display-lvgl); only display-lvgl.md held real content.

Per direction from the maintainer: rather than restoring the full hand-ported LVGL content, display-lvgl.md is now an honest placeholder instead. A separate in-progress firmware PR is adding real /*luadoc*/ annotations for every LVGL function directly to api_colorlcd_lvgl.cpp; once that lands, this page should be regenerated from source like every other page, not hand-maintained content that would need throwing away almost immediately. The placeholder explains this and that the ~30 lvgl-*.md function pages (still present on disk, untouched) aren't linked from here in the meantime.

2. Investigated the reported ~87 unknown-type regression in the LuaLS output. Traced 28 affected items: 26 have raw /*luadoc*/ comment text that genuinely differs between the old dev-branch snapshot and real 2.12 -- the real firmware comments lack an explicit type token (e.g. (integer)) that the dev branch had. That's an accurate reflection of real 2.12 being less precisely annotated, not a pipeline bug, and isn't something to silently "fix" by reverting to the wrong-branch data. The other 2 (lcd.drawText, lcd.drawNumber) looked like a parser regression at first (identical raw_luadoc between old/new models) but traced to a merge_item() quirk: these symbols are documented in two source files (api_stdlcd.cpp and api_colorlcd.cpp), and merge_item displays whichever raw text is longer while merging parameters from whichever block has more of them -- so the displayed raw_luadoc didn't reflect the block that actually determines the regressed parameter's type. Checked that block directly on real 2.12: same root cause as the other 26 (no type token in the source), just obscured by which merged block happens to get shown. No parser fix needed either way.

3. Added a conservative, report-only stale-page sweep (build --report-unowned) rather than an automatic delete, given how easily #1 demonstrated the "what does the pipeline own" boundary can be gotten wrong. Lists any .md file not accounted for by the current model, for manual review -- never deletes anything. Currently only flags the 45 known lvgl-*.md pages, as expected.

4. Removed the "constants" group from api-groups.json entirely (confirmed zero items, nothing references its page) so a future rebuild can't resurrect the empty stub that PR #3 deliberately deleted -- this PR's original rebuild had inadvertently undone that.

Both mkdocs build --strict (public + dev configs) still pass clean, zero warnings, after these fixes.

Test plan

• mkdocs build --strict -f mkdocs.yml -- exit 0, zero warnings
• mkdocs build --strict -f mkdocs.dev.yml -- exit 0, zero warnings
• Confirmed end-to-end against real built HTML: site/api-reference/audio-sound/flush-audio/index.html exists, hub card hrefs resolve correctly
• page_href hand-verified against every from/to page-kind combination (hub<->item, item<->module-dashboard, index<->hub) before trusting the empirical build check
• Confirmed zero uncategorized items after the group-taxonomy fix (was 1: screenshot)
• Confirmed overlay content (docs-system/overlays/*.md) survived the rebuild
• Confirmed all 45 lvgl-*.md pages still exist on disk, untouched (separate PR docs: port real LVGL function docs from the official guide #5)
• Rebased on top of fix: repair broken internal links across four patterns #2, docs: resolve nav-orphan pages #3, docs: split mkdocs config into public/dev (Finding 4) #4 to confirm no bundling of unrelated changes; does not depend on unmerged docs: port real LVGL function docs from the official guide #5
• display-lvgl.md no longer clobbered on rebuild; verified with a fresh restore-then-rebuild cycle
• build --report-unowned sweep verified against live content: only the 45 known lvgl-*.md files flagged, zero false positives

🤖 Generated with Claude Code

https://claude.ai/code/session_015yCHydHbzZYCKpav38SonD

[pfeerick]

Update: addressed code review findings

Pushed a follow-up commit (9931ac73) fixing four issues a review pass found in this PR:

1. Critical — display-lvgl.md was silently clobbered. build_outputs() unconditionally regenerates every group's hub page from the model, including zero-item groups — and "display-lvgl" has zero extracted items (LVGL firmware has no luadoc annotations at all), so the original rebuild overwrote the hand-authored hub page with the generic empty-group stub. Fixed build_outputs so a zero-item group's existing real content is never overwritten or deleted by the stale-page cleanup pass (which ran before the per-group write loop and would unlink it regardless of any check placed after — had to move the check earlier). Verified only two groups currently have zero items (constants, display-lvgl); only display-lvgl.md held real content.

Per updated direction from the user: rather than restoring the full hand-ported LVGL content, display-lvgl.md is now an honest placeholder. A separate in-progress firmware PR is adding real /*luadoc*/ annotations for every LVGL function directly to api_colorlcd_lvgl.cpp; once that lands, this page should be regenerated from source like every other page, not hand-maintained content that would immediately need throwing away. The placeholder explains this and that the ~30 lvgl-*.md function pages (still present on disk) aren't linked from here in the meantime.

2. Investigated the ~87 unknown-type regression. Traced 28 affected items: 26 have raw /*luadoc*/ text that genuinely differs between the old dev-branch snapshot and real 2.12 — the real firmware comments lack an explicit type token (e.g. (integer)) that the dev branch had. That's an accurate reflection of real 2.12 being less precisely annotated, not a pipeline bug, and shouldn't be silently "fixed" by reverting to the wrong-branch data. The other 2 (lcd.drawText, lcd.drawNumber) looked like a parser regression at first (identical raw_luadoc between models) but traced to a merge_item() quirk: these symbols are documented in two source files, and merge_item displays whichever raw text is longer while merging parameters from whichever block has more of them — so the displayed text didn't reflect the block that actually determines the regressed parameter's type. Checked that block directly on real 2.12: same root cause as the other 26, just obscured by which merged block happens to get shown. No parser fix needed either way.

3. Added a conservative, report-only stale-page sweep (build --report-unowned) rather than an automatic delete, given how easily #1 demonstrated the "what does the pipeline own" boundary can be gotten wrong. Lists any .md file not accounted for by the current model, for manual review — never deletes. Currently only flags the 45 known lvgl-*.md pages, as expected.

4. Removed the "constants" group from api-groups.json entirely (confirmed zero items, nothing references its page) so a future rebuild can't resurrect the empty stub that PR #3 deliberately deleted.

Also re-fixed the same recurring assets/luals/*.d.lua broken-link regression from the previous commit — repeated build runs while investigating these findings regenerated it again from the still-unfixed raw upstream comments (this will keep recurring until that upstream firmware fix lands, per the note already in REAL-EXTRACTION-NOTES.md).

Both mkdocs build --strict (public + dev configs) still pass clean, zero warnings.

🤖 Generated with Claude Code

https://claude.ai/code/session_015yCHydHbzZYCKpav38SonD

[pfeerick]

Follow-up: re-extracted against the corrected 2.12 tip.

The model committed in the previous fix (9931ac73) was extracted from 2.12@0e3b4115c3 — one commit before EdgeTX/edgetx#7770 (backported as 16713095a1) fixed 28 functions' worth of broken doc-site links directly in the firmware /*luadoc*/ comments. website/md-docs/assets/luals/lcd.d.lua/runtime.d.lua only had correct links at that point because of a manual patch layered on top of a stale extraction — confirmed by re-running build from that checked-in model, which silently reverted them back to broken.

Re-extracted from 2.12@16713095a1 (current tip) and rebuilt (af867548). Same 153 items, same review backlog/decision counts. Diff is scoped to exactly the 28 previously-patched functions' pages (+ their review-*.md copies) and the two .d.lua files — now correct straight from source, no manual patch needed. Confirmed display-lvgl.md (LVGL placeholder) and api-groups.json (dead constants group removal) are both untouched by this — neither regressed. Both mkdocs build --strict configs still pass clean.

🤖 Generated with Claude Code

https://claude.ai/code/session_015yCHydHbzZYCKpav38SonD