Website: generate the user guide's key tables from the Apps' own help lists #72

New Issue

2026-10-06T23:29:55Z

twisla commented

2026-10-06 23:29:55 +00:00

Follow-up to #69 (Q202). Every App now declares its keys for the state it is in (App::help(), KeyHelp rows), and the help panel shows them on the device. The user guide's key tables on the website are still written by hand (site/content/guide/*.md), so the two can drift.

Idea: generate the guide's key tables from the same lists, as site/tools/gen_dev_docs.py already does for the command reference (from kHelp) and the ADRs.

What makes it less than trivial: the lists are built in C++ at run time, per state (if (view_ == …) out.push_back({…})), in src/apps, which doesn't compile on a PC. Options for a design round:

move each App's lists into constant tables in a header that a script can parse, with the state as the table's name;
or have the firmware print them (help dump over the console) and commit the result, checked in CI like the other generated pages;
or keep the prose by hand and generate only a compact "all keys" reference page.

Done when (to be refined): a key added to an App shows up on the website without anyone editing a guide page, and CI fails when the generated page is out of date.

Follow-up to #69 (Q202). Every App now declares its keys for the state it is in (`App::help()`, `KeyHelp` rows), and the help panel shows them on the device. The **user guide's key tables on the website are still written by hand** (`site/content/guide/*.md`), so the two can drift. Idea: generate the guide's key tables from the same lists, as `site/tools/gen_dev_docs.py` already does for the command reference (from `kHelp`) and the ADRs. **What makes it less than trivial:** the lists are built in C++ at run time, per state (`if (view_ == …) out.push_back({…})`), in `src/apps`, which doesn't compile on a PC. Options for a design round: - move each App's lists into constant tables in a header that a script can parse, with the state as the table's name; - or have the firmware print them (`help dump` over the console) and commit the result, checked in CI like the other generated pages; - or keep the prose by hand and generate only a compact "all keys" reference page. **Done when (to be refined):** a key added to an App shows up on the website without anyone editing a guide page, and CI fails when the generated page is out of date.

twisla added this to the W1 Website milestone 2026-10-06 23:29:55 +00:00

twisla added the

area/website labels 2026-10-06 23:29:55 +00:00

twisla referenced this issue

2026-10-06 23:30:07 +00:00

Help: Fn+h lists the keys of the screen you're on; no screen names its keys any more (#69) #73

twisla referenced this issue from a commit

2026-10-06 23:42:53 +00:00

Keys: one table file for the device's help panel and the website's key tables (#72)

twisla referenced this issue

2026-10-06 23:42:54 +00:00

Keys: one table file for the device's help panel and the website's key tables (#72) #75

twisla referenced this issue

2026-10-06 23:47:36 +00:00

Help: one global shortcut that shows the current screen's key bindings, and no more hint lines #69

twisla referenced this issue

2026-10-06 23:47:37 +00:00

Website: a project site with docs, how-tos and an FAQ #12

twisla referenced this issue from a commit

2026-10-06 23:50:59 +00:00

Merge pull request 'Keys: one table file for the device's help panel and the website's key tables (#72)' (#75) from keys-tables into main

twisla commented

2026-10-06 23:51:00 +00:00

Done in pull request #75, merged into main.

Every screen's keys are constant tables in lib/core/src/app_keys.h (52 tables, each under a comment // id: Title). The device's help panel shows the table of the state an App is in.
site/tools/gen_dev_docs.py reads the same file and writes site/data/keys.toml. The keys shortcode puts a screen's tables on its guide page, and /guide/keys/ lists all of them.
The Site job fails when the data file is out of date or a page asks for a table that doesn't exist, and it runs when app_keys.h changes. A key added to an App shows up on the website without anyone editing a page.

Of the three options in the issue this is the first (constant tables a script can read). It cost three rows their second wording, since a table can't change with the state: GNSS's Tab and r, and the Scanner's c, now say both things they do.

Left as it was: the guide's hand-written tables, where they say more than a key list can. They can still drift; the generated ones under them are the reference.

Done in pull request #75, merged into `main`. - Every screen's keys are constant tables in **`lib/core/src/app_keys.h`** (52 tables, each under a comment `// id: Title`). The device's help panel shows the table of the state an App is in. - `site/tools/gen_dev_docs.py` reads the same file and writes `site/data/keys.toml`. The **`keys` shortcode** puts a screen's tables on its guide page, and **`/guide/keys/`** lists all of them. - The Site job fails when the data file is out of date or a page asks for a table that doesn't exist, and it runs when `app_keys.h` changes. A key added to an App shows up on the website without anyone editing a page. Of the three options in the issue this is the first (constant tables a script can read). It cost three rows their second wording, since a table can't change with the state: GNSS's `Tab` and `r`, and the Scanner's `c`, now say both things they do. **Left as it was:** the guide's hand-written tables, where they say more than a key list can. They can still drift; the generated ones under them are the reference.

twisla closed this issue

2026-10-06 23:51:01 +00:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: twisla/roro9stack#72