Skip to content

docs: port real LVGL function docs from the official guide - #5

Closed
pfeerick wants to merge 1 commit into
edgetx_2.12from
docs/port-lvgl-from-official-guide
Closed

docs: port real LVGL function docs from the official guide#5
pfeerick wants to merge 1 commit into
edgetx_2.12from
docs/port-lvgl-from-official-guide

Conversation

@pfeerick

@pfeerick pfeerick commented Sep 7, 2026

Copy link
Copy Markdown
Collaborator

Summary

The firmware has zero /*luadoc*/ annotations for any of the 45 lvgl.* Lua bindings (radio/src/lua/api_colorlcd_lvgl.cpp), so this repo's source-extraction pipeline had nothing to extract for the LVGL section and fell back to a generic template for all 42 constructor pages that have an official-guide counterpart: a bare params (table) placeholder, an untyped bullet list of key names, and — on every single page — Since: 3.0.0, which is factually wrong.

The official EdgeTX/lua-reference-guide's LVGL docs aren't guesswork either way: they were written by GitHub user phil.a.mitchell, who is almost certainly the same person as philmoz, the primary author (19 of 22 commits) of api_colorlcd_lvgl.cpp itself — i.e. the implementer wrote the docs. That content has full parameter tables (name/type/description/default), return values, behavioral notes, and real per-function "Introduced in 2.11.0"-style version history. I spot-checked it against current firmware and confirmed it's accurate through the v2.11.7 tag: the CHOICE constant spelling (firmware had a CHOIDE typo at one point, fixed later — the docs already show the correct spelling) and the borderPad/align/menu/edited property additions (2.11.4–2.11.6) are all already correctly reflected there.

This ports all 42 matching function pages from EdgeTX/lua-reference-guide's edgetx_2.11 branch (lua-api-reference/lvgl-for-lua/lvgl.*.md) into this repo's page format (H1 + syntax + description, ## Parameters table, ## Returns, ## Availability, ## Notes, ## Source). Fixed two source typos along the way rather than porting them forward: a missing ( on ~28 "create an object" syntax lines (e.g. lvgl.arc\[parent]...lvgl.arc([parent]...) and a doubled-brace typo on lvgl.build's syntax line.

Not touched:

  • lvgl-close.md, lvgl-disable.md, lvgl-enable.md — real functions (confirmed via LROT_FUNCENTRY in current firmware) added after the official guide's content was written, with no official counterpart to port from. Left as-is.
  • programming/core-concepts/lvgl-for-lua.md and api-overview/constants/lvgl-constants.md — unlike the per-function pages, these were already good, hand-written content covering the same ground as the official guide's overview.md/api.md/constants.md/examples.md, including the same 2.11.4/2.11.5 version callouts. No changes needed.

Known drift: ~40 commits have landed on main since the v2.11.7 tag touching api_colorlcd_lvgl.cpp/lua_lvgl_widget.cpp — real additions/fixes (e.g. negative rectangle width/height, further choice/textEdit value-setting capability, additional arc properties) not reflected in this port, since the source it's built from is itself only verified through v2.11.7. Closing that gap needs either a fresh diff pass against current main, or better, the firmware author adding real /*luadoc*/ annotations to api_colorlcd_lvgl.cpp so this pipeline can extract it directly instead of another manual port.

Test plan

  • Verified 42/42 official function pages map 1:1 to fork pages (no orphans on either side beyond the 3 real fork-only additions)
  • Spot-checked CHOICE spelling and borderPad/align/menu/edited version callouts against current firmware to confirm the ported content is accurate through v2.11.7
  • mkdocs build --strict -f mkdocs.yml — exit 0, zero warnings
  • mkdocs build --strict -f mkdocs.dev.yml — exit 0, zero warnings

🤖 Generated with Claude Code

https://claude.ai/code/session_015yCHydHbzZYCKpav38SonD

The firmware has zero /*luadoc*/ annotations for any of the 45 lvgl.*
Lua bindings (radio/src/lua/api_colorlcd_lvgl.cpp), so this repo's
source-extraction pipeline had nothing to extract for the LVGL
section and fell back to a generic template for all 42 constructor
pages that have an official-guide counterpart: a bare "params (table)
object definition table" placeholder, an untyped bullet list of key
names, and -- on every single page -- "Since: 3.0.0", which is wrong.

The official EdgeTX/lua-reference-guide's LVGL docs are not guesswork
either way: they were written by GitHub user phil.a.mitchell, who is
almost certainly the same person as philmoz, the primary author (19
of 22 commits) of api_colorlcd_lvgl.cpp itself. That content has full
parameter tables (name/type/description/default), return values,
behavioral notes, and real per-function "Introduced in 2.11.0" style
version history -- verified accurate against the firmware source
through the v2.11.7 tag (spot-checked: the CHOICE constant spelling
fix and the borderPad/align/menu/edited property additions are all
already correctly reflected there).

This ports all 42 matching function pages from
EdgeTX/lua-reference-guide's edgetx_2.11 branch
(lua-api-reference/lvgl-for-lua/lvgl.*.md) into this repo's page
format (H1 + syntax + description, Parameters table, Returns,
Availability, Notes, Source), fixing two source typos along the way
rather than porting them forward: a missing '(' on ~28 "create an
object" syntax lines (e.g. "lvgl.arc\[parent]..." ->
"lvgl.arc([parent]...") and a doubled-brace typo on lvgl.build's
syntax line.

Not touched:
- lvgl-close.md, lvgl-disable.md, lvgl-enable.md: real functions
  (confirmed via LROT_FUNCENTRY in current firmware) added after the
  official guide's content was written, with no official counterpart
  to port from. They keep their existing stub content.
- website/md-docs/programming/core-concepts/lvgl-for-lua.md and
  website/md-docs/api-overview/constants/lvgl-constants.md: unlike
  the per-function pages, these were already good hand-written
  content covering the same ground as the official guide's
  overview.md/api.md/constants.md/examples.md, including the same
  2.11.4/2.11.5 version callouts. No changes needed.

Known drift: ~40 commits have landed on main since the v2.11.7 tag
touching api_colorlcd_lvgl.cpp / lua_lvgl_widget.cpp -- real
additions/fixes (e.g. negative rectangle width/height, further
choice/textEdit value-setting capability, additional arc properties)
not reflected in this port, since the source it's built from is
itself a snapshot verified only through v2.11.7. Closing that gap
needs either a fresh diff pass against current main or, better, the
firmware author adding real /*luadoc*/ annotations to
api_colorlcd_lvgl.cpp so this pipeline can extract it directly instead
of another manual GitBook-to-page port.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015yCHydHbzZYCKpav38SonD
@pfeerick

pfeerick commented Sep 8, 2026

Copy link
Copy Markdown
Collaborator Author

Superseded: the goal here (accurate LVGL docs instead of the placeholder "Since: 3.0.0" content) is now achieved via real extraction instead of a manual port. EdgeTX/edgetx#7771 adds proper /luadoc/ annotations for all 45 lvgl.* functions, and the pipeline can now parse them correctly (commits a408cce, 5c5014b on edgetx_2.12 — the indentation-anchored regex bug and the flattened-bullet-list table rendering that were blocking this). Once #7771 lands and the extracted content replaces the current hand-preserved lvgl-*.md pages, this manual port is no longer needed — the whole point of #7771 landing is to make ports like this one unnecessary going forward.

@pfeerick pfeerick closed this Sep 8, 2026
pfeerick added a commit that referenced this pull request Sep 9, 2026
Re-extracted from EdgeTX/edgetx branch 2.12 at 8718d2473a (the squash
merge of #7771, "add luadoc annotations for the LVGL Lua API"): 153 ->
198 items, all 45 real. The 44 hand-preserved flat lvgl-*.md pages
(ported from the official guide, since firmware had zero LVGL
annotations at all -- see prior HANDOFF.md entries) are replaced with
real nested display-lvgl/<item>.md pages generated the same way as
every other group now; the old flat files are removed, not left as
orphans.

Both #5 (the manual port) and #7 (the @common/@commonparams support
this depended on, already ported separately) on
JimB40/lua-reference-guide are closed as superseded by this.

docs-system/generated/api-model.local.json, REAL-EXTRACTION-NOTES.md
(both copies), and HANDOFF.md updated to match.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HLXbKn4rY3NihRnqH89jmD
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant