Skip to content

docs: document the code generation scripts - #7604

Merged
pfeerick merged 2 commits into
mainfrom
pfeerick/docs-codegen
Aug 11, 2026
Merged

docs: document the code generation scripts#7604
pfeerick merged 2 commits into
mainfrom
pfeerick/docs-codegen

Conversation

@pfeerick

@pfeerick pfeerick commented Aug 1, 2026

Copy link
Copy Markdown
Member

Summary

Three scripts in the tree generate source files that are committed to git, and the build never runs them. Two of the three were completely undocumented — no mention in docs/, any workflow, or a README:

Generator Produces
radio/src/fonts/lvgl/make_fonts.sh radio/src/fonts/lvgl/{std,sml,lrg}/lv_font_*.c
tools/cfn_sorter.sh radio/src/cfn_sort.cpp
tools/generate-yaml.sh radio/src/storage/yaml/yaml_datastructs_*.cpp

So there was no way to discover that editing radio/src/translations/i18n/*.h requires re-running two of them, or that their output is committed rather than built.

Adds a Code Generation page covering all three — inputs, prerequisites, and the dev container invocation — and cross-links it from the existing YAML parser page.

The page is deliberately precise about when each generator actually needs re-running, since both translation-driven ones are narrower than they look:

  • cfn_sorter.cpp reads only the 25 TR_SF_* special function names, so editing any other translated string leaves cfn_sort.cpp untouched.
  • The fonts only change if a translation introduces a character the font does not already contain, and only for cn/tw/jp/he/ko/ru/ua — Latin-script translations never affect them.

Both were verified by editing a string of each kind and re-running the generator.

Second commit

docs/building/windows.md pinned Qt 6.9.0 in three places (the QT_DIR path, the prose, and the aqt install-qt command). CI builds Companion for Windows against 6.9.3 — the qt-version default in .github/actions/build_companion/action.yml, which no workflow overrides — as do the Linux setup scripts and the dev container image. Updated to match.

Note

The new page mentions that tools/setup_buildenv_ubuntu*.sh install the required locales, which is true as of #7603. If this merges first, that one sentence is briefly ahead of reality.

Testing

mkdocs build --strict passes, which is what CI runs. No orphaned pages and no broken nav entries.

🤖 Generated with Claude Code

pfeerick and others added 2 commits August 2, 2026 09:26
make_fonts.sh and cfn_sorter.sh were undocumented, so there was no way to
discover that editing radio/src/translations/i18n/*.h requires re-running
them, or that their output is committed rather than built.

Add a Code Generation page covering all three generators - the LVGL fonts,
the custom function sort order and the YAML parsers - with their inputs,
prerequisites and the dev container invocation, and cross-link it from the
existing YAML parser page.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The page pinned Qt 6.9.0 in the QT_DIR path, the prose and the aqt
install-qt command, while CI builds Companion for Windows against 6.9.3
(the qt-version default in .github/actions/build_companion/action.yml).
The Linux setup scripts and the dev container image also use 6.9.3.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
@pfeerick pfeerick added this to the 2.12.3 milestone Aug 1, 2026
@pfeerick pfeerick added documentation 📝 Improvements or additions to documentation backport/2.12 To be backported to a 2.12 release also. labels Aug 1, 2026
@pfeerick
pfeerick merged commit 4822400 into main Aug 11, 2026
2 checks passed
@pfeerick
pfeerick deleted the pfeerick/docs-codegen branch August 11, 2026 21:26
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

backport/2.12 To be backported to a 2.12 release also. documentation 📝 Improvements or additions to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant