docs: resolve nav-orphan pages - #3
Merged
Merged
Conversation
Wires api-overview/constants/key_events.md into nav under API Overview
> Constants as "Key Event Mechanism", right after Key Event Constants.
It was built but unreachable from nav despite having real, unique
content (the FIRST/LONG/REPEAT/BREAK key-event mechanism explainer)
that isn't covered anywhere else. Its constants table overlaps with
key-event-constants.md's cleaner reference table; reconciling that
duplication is left as a follow-up editorial decision rather than
bundled into this mechanical nav fix.
Also deletes api-reference/constants.md, an empty auto-generated stub
("No extracted APIs are assigned to this group yet") that was never
wired into nav and isn't linked from anywhere else in the site.
module-*.md dashboards and radios/tbs/README.md (also flagged as
nav-orphans in the pre-merge gap analysis) need no action here:
module-*.md is already addressed by the separate mkdocs.yml/
mkdocs.dev.yml public/dev split, and radios/tbs/README.md is
correctly hidden pending real TBS radio model content.
Verified with `mkdocs build --strict` (exit 0, zero warnings).
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015yCHydHbzZYCKpav38SonD
This was referenced Sep 7, 2026
pfeerick
added a commit
that referenced
this pull request
Sep 7, 2026
1. Critical: build_outputs() unconditionally regenerated every group's
hub page from the model, including "display-lvgl" (zero extracted
items, since LVGL firmware has no luadoc annotations at all) --
this silently clobbered the hand-authored display-lvgl.md with the
generic empty-group stub. Fixed build_outputs so a zero-item
group's existing page is never overwritten (or deleted by the
stale-page cleanup pass, which ran before the per-group write loop
and would have unlinked it regardless of any check placed after)
unless that existing content already matches the stub text.
Verified no other hub page was affected: exactly two groups
("constants", "display-lvgl") currently have zero items, and only
display-lvgl.md held real content.
Per updated direction: display-lvgl.md is not restored to its full
hand-ported content, since a separate in-progress firmware PR will
add real /*luadoc*/ annotations for every LVGL function directly to
api_colorlcd_lvgl.cpp, after which this page should be regenerated
from source like every other page rather than hand-maintained.
Replaced with an honest placeholder explaining the LVGL page and
its ~30 function pages are pending that firmware work, rather than
the misleading "no APIs assigned" stub or a soon-to-be-replaced
full copy.
2. Investigated the LuaLS type-annotation regression from re-extracting
against the real 2.12 branch: found 28 items where a param/return
type dropped to "unknown". For 26 of them, the raw upstream
/*luadoc*/ comment text genuinely differs between branches -- real
2.12 firmware lacks an explicit type token (e.g. "(integer)") that
the old cpm-tlm-sim-fix dev-branch snapshot had. That's an accurate
reflection of real 2.12 being less precisely annotated, not a
pipeline bug, and is not something to silently "fix" by reverting
to the wrong-branch data.
The other 2 (lcd.drawText, lcd.drawNumber) initially looked like a
parser regression (identical raw_luadoc between old/new models) but
traced to a real quirk in merge_item(): these symbols are
documented in two source files (api_stdlcd.cpp without an
inversColor parameter, api_colorlcd.cpp with one), and merge_item
keeps whichever raw_luadoc text is longer for display while merging
parameter lists from whichever block has more parameters -- so the
displayed raw_luadoc didn't reflect the block that actually
determines inversColor's type. Checked api_colorlcd.cpp on real
2.12 directly: `@param inversColor (optional with the INVERS flag)
...` has no type token either. Same root cause as the other 26,
just obscured by which merged block happens to get shown. No parser
fix needed.
3. Added a conservative, report-only stale-page sweep (`build
--report-unowned`) rather than an automatic delete: after building,
lists any .md file under --docs-output not accounted for by the
current model (not an index/review/module/group page, not an item
page, not a preserved zero-item group page), for manual review.
Never deletes anything -- some listed files may be legitimate
hand-authored content with no model backing (confirmed: currently
only the 45 known lvgl-*.md pages show up), some may be genuine
orphans from a prior run under a different naming scheme or group
assignment, and telling those apart automatically isn't safe to do
with full confidence yet.
4. Removed the "constants" group from api-groups.json entirely (zero
items, confirmed nothing references its page) -- this PR's rebuild
had regenerated api-reference/constants.md, undoing its deliberate
deletion in #3. Removing the group definition (rather than just
deleting the page again) means a future rebuild can't resurrect it.
Also re-fixes the same recurring assets/luals/*.d.lua broken-link
regression documented in the previous commit -- repeated build runs
while investigating these findings regenerated the LuaLS files from
the still-unfixed raw upstream comments again.
Verified: `mkdocs build --strict` passes with zero warnings on both
mkdocs.yml and mkdocs.dev.yml. Confirmed all 45 lvgl-*.md pages still
exist on disk (just not linked from the temporary display-lvgl.md
placeholder). Confirmed zero uncategorized items after removing the
constants group.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015yCHydHbzZYCKpav38SonD
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Follow-up to #2, resolving the nav-orphan pages flagged in Finding 2 of the pre-merge gap analysis (pages that build but aren't reachable from
nav):api-overview/constants/key_events.md— wired into nav under API Overview > Constants as "Key Event Mechanism", right after Key Event Constants. It had real, unique content (the FIRST/LONG/REPEAT/BREAK key-event mechanism explainer) not covered anywhere else, but was never linked from nav. Note: its own EVT_* constants table overlaps withkey-event-constants.md's cleaner reference table — reconciling that duplication is left as a follow-up editorial call rather than bundled into this nav fix.api-reference/constants.md— deleted. Empty auto-generated stub ("No extracted APIs are assigned to this group yet"), never in nav, not linked from anywhere else.module-*.mddashboards — no action needed; already addressed by the plannedmkdocs.yml/mkdocs.dev.ymlpublic/dev split (separate change).radios/tbs/README.md— no action needed; correctly commented out of nav pending real TBS radio model content (it's currently just an empty table with two commented-out placeholder rows).Test plan
api-reference/constants.mdbefore deleting itmkdocs build --strict— exit 0, zero warnings🤖 Generated with Claude Code
https://claude.ai/code/session_015yCHydHbzZYCKpav38SonD