User-facing docs: --commands-md flag, doc/user/ tree, anonymised script.

- `essim --commands-md [file]` instantiates the Tui, calls
  `Tui::DumpCommandsMd(ostream&)` which iterates the live registry and
  emits Markdown grouped by interactive/other, then exits. Single
  source of truth: a new `CommandSpec` field surfaces automatically.
- CMake `doc` target now `DEPENDS essim` and chains:
    doxygen → gen_api_md.py → doc/api/
    essim --commands-md      → doc/user/commands.md
- `doc/user/` adds:
    - index.md (hand-written) — first session, interactive-screen
      conventions, save/restore/replay overview.
    - scripting.md (hand-written) — `set`/`$var` expansion semantics,
      `source` event-paced execution, script-save denylist, worked
      example pointing at test/system.essim.
    - commands.md (auto-generated, regenerated by the `doc` target).
- Top-level README refocused on quick start; pointers to the new
  doc tree (user/, api/, DESIGN.md) instead of an inline command table.
- doc/README.md and DESIGN.md document the two-pipeline doc workflow.
- `test/system.essim` and user docs anonymised: bkp → backplane,
  vdn1/2/3 → payload1/2/3, cb3p → payload4, bpb/cob/ssu →
  peripheral1/2/3; netlist file names + variable names + paths all
  replaced with generic equivalents.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
2026-05-12 08:29:45 +02:00
parent 66460262af
commit 043fef0a31
16 changed files with 825 additions and 242 deletions

View File

@@ -2,395 +2,399 @@
`class Tui`
Defined in [tui.hpp:17](../../../../src/tui/tui.hpp#L17)
Defined in [tui.hpp:18](../../../../src/tui/tui.hpp#L18)
## Private type
### `enum Completion`
📍 [tui.hpp:18](../../../../src/tui/tui.hpp#L18)
📍 [tui.hpp:19](../../../../src/tui/tui.hpp#L19)
## Private Attributes
### `std::vector< std::string > history`
📍 [tui.hpp:40](../../../../src/tui/tui.hpp#L40)
📍 [tui.hpp:41](../../../../src/tui/tui.hpp#L41)
### `std::vector< std::string > recorded`
📍 [tui.hpp:41](../../../../src/tui/tui.hpp#L41)
📍 [tui.hpp:42](../../../../src/tui/tui.hpp#L42)
### `std::vector< std::string > output`
📍 [tui.hpp:42](../../../../src/tui/tui.hpp#L42)
📍 [tui.hpp:43](../../../../src/tui/tui.hpp#L43)
### `std::string input`
📍 [tui.hpp:43](../../../../src/tui/tui.hpp#L43)
📍 [tui.hpp:44](../../../../src/tui/tui.hpp#L44)
### `int cursor_pos`
📍 [tui.hpp:44](../../../../src/tui/tui.hpp#L44)
📍 [tui.hpp:45](../../../../src/tui/tui.hpp#L45)
### `int history_idx`
📍 [tui.hpp:45](../../../../src/tui/tui.hpp#L45)
📍 [tui.hpp:46](../../../../src/tui/tui.hpp#L46)
### `int scroll_offset`
📍 [tui.hpp:46](../../../../src/tui/tui.hpp#L46)
📍 [tui.hpp:47](../../../../src/tui/tui.hpp#L47)
Lines scrolled up from the tail; 0 = follow newest output.
### `bool quit`
📍 [tui.hpp:47](../../../../src/tui/tui.hpp#L47)
📍 [tui.hpp:48](../../../../src/tui/tui.hpp#L48)
### `bool in_source`
📍 [tui.hpp:48](../../../../src/tui/tui.hpp#L48)
📍 [tui.hpp:49](../../../../src/tui/tui.hpp#L49)
### `std::unique_ptr< System > sys`
📍 [tui.hpp:50](../../../../src/tui/tui.hpp#L50)
📍 [tui.hpp:51](../../../../src/tui/tui.hpp#L51)
### `std::deque< Prompt > pending`
📍 [tui.hpp:51](../../../../src/tui/tui.hpp#L51)
📍 [tui.hpp:52](../../../../src/tui/tui.hpp#L52)
### `std::map< std::string, CommandSpec > commands`
📍 [tui.hpp:52](../../../../src/tui/tui.hpp#L52)
📍 [tui.hpp:53](../../../../src/tui/tui.hpp#L53)
### `std::map< std::string, std::string > vars`
📍 [tui.hpp:53](../../../../src/tui/tui.hpp#L53)
📍 [tui.hpp:54](../../../../src/tui/tui.hpp#L54)
$var-style substitution table.
### `int screen_idx`
📍 [tui.hpp:56](../../../../src/tui/tui.hpp#L56)
📍 [tui.hpp:57](../../../../src/tui/tui.hpp#L57)
### `std::vector< std::string > search_modules`
📍 [tui.hpp:59](../../../../src/tui/tui.hpp#L59)
📍 [tui.hpp:60](../../../../src/tui/tui.hpp#L60)
### `std::vector< std::string > search_types`
📍 [tui.hpp:60](../../../../src/tui/tui.hpp#L60)
📍 [tui.hpp:61](../../../../src/tui/tui.hpp#L61)
### `int search_module_idx`
📍 [tui.hpp:61](../../../../src/tui/tui.hpp#L61)
📍 [tui.hpp:62](../../../../src/tui/tui.hpp#L62)
### `int search_type_idx`
📍 [tui.hpp:62](../../../../src/tui/tui.hpp#L62)
📍 [tui.hpp:63](../../../../src/tui/tui.hpp#L63)
### `int search_focus_idx`
📍 [tui.hpp:63](../../../../src/tui/tui.hpp#L63)
📍 [tui.hpp:64](../../../../src/tui/tui.hpp#L64)
### `std::string search_query`
📍 [tui.hpp:64](../../../../src/tui/tui.hpp#L64)
📍 [tui.hpp:65](../../../../src/tui/tui.hpp#L65)
### `std::vector< std::string > connect_modules`
📍 [tui.hpp:67](../../../../src/tui/tui.hpp#L67)
📍 [tui.hpp:68](../../../../src/tui/tui.hpp#L68)
### `int connect_m1_idx`
📍 [tui.hpp:68](../../../../src/tui/tui.hpp#L68)
📍 [tui.hpp:69](../../../../src/tui/tui.hpp#L69)
### `int connect_m2_idx`
📍 [tui.hpp:69](../../../../src/tui/tui.hpp#L69)
📍 [tui.hpp:70](../../../../src/tui/tui.hpp#L70)
### `std::string connect_p1_filter`
📍 [tui.hpp:70](../../../../src/tui/tui.hpp#L70)
📍 [tui.hpp:71](../../../../src/tui/tui.hpp#L71)
### `std::string connect_p2_filter`
📍 [tui.hpp:71](../../../../src/tui/tui.hpp#L71)
📍 [tui.hpp:72](../../../../src/tui/tui.hpp#L72)
### `std::vector< std::string > connect_p1_list`
📍 [tui.hpp:72](../../../../src/tui/tui.hpp#L72)
📍 [tui.hpp:73](../../../../src/tui/tui.hpp#L73)
### `std::vector< std::string > connect_p2_list`
📍 [tui.hpp:73](../../../../src/tui/tui.hpp#L73)
📍 [tui.hpp:74](../../../../src/tui/tui.hpp#L74)
### `int connect_p1_idx`
📍 [tui.hpp:74](../../../../src/tui/tui.hpp#L74)
📍 [tui.hpp:75](../../../../src/tui/tui.hpp#L75)
### `int connect_p2_idx`
📍 [tui.hpp:75](../../../../src/tui/tui.hpp#L75)
📍 [tui.hpp:76](../../../../src/tui/tui.hpp#L76)
### `int connect_focus_idx`
📍 [tui.hpp:76](../../../../src/tui/tui.hpp#L76)
📍 [tui.hpp:77](../../../../src/tui/tui.hpp#L77)
### `std::vector< std::string > explore_modules`
📍 [tui.hpp:79](../../../../src/tui/tui.hpp#L79)
📍 [tui.hpp:80](../../../../src/tui/tui.hpp#L80)
### `int explore_module_idx`
📍 [tui.hpp:80](../../../../src/tui/tui.hpp#L80)
📍 [tui.hpp:81](../../../../src/tui/tui.hpp#L81)
### `std::vector< std::string > explore_types`
📍 [tui.hpp:81](../../../../src/tui/tui.hpp#L81)
📍 [tui.hpp:82](../../../../src/tui/tui.hpp#L82)
### `int explore_type_idx`
📍 [tui.hpp:82](../../../../src/tui/tui.hpp#L82)
📍 [tui.hpp:83](../../../../src/tui/tui.hpp#L83)
### `std::vector< std::string > explore_children`
📍 [tui.hpp:83](../../../../src/tui/tui.hpp#L83)
📍 [tui.hpp:84](../../../../src/tui/tui.hpp#L84)
### `int explore_child_idx`
📍 [tui.hpp:84](../../../../src/tui/tui.hpp#L84)
📍 [tui.hpp:85](../../../../src/tui/tui.hpp#L85)
### `std::string explore_child_filter`
📍 [tui.hpp:85](../../../../src/tui/tui.hpp#L85)
📍 [tui.hpp:86](../../../../src/tui/tui.hpp#L86)
### `std::string explore_detail_filter`
📍 [tui.hpp:86](../../../../src/tui/tui.hpp#L86)
📍 [tui.hpp:87](../../../../src/tui/tui.hpp#L87)
### `std::vector< std::string > explore_detail`
📍 [tui.hpp:87](../../../../src/tui/tui.hpp#L87)
📍 [tui.hpp:88](../../../../src/tui/tui.hpp#L88)
### `int explore_detail_idx`
📍 [tui.hpp:88](../../../../src/tui/tui.hpp#L88)
📍 [tui.hpp:89](../../../../src/tui/tui.hpp#L89)
### `std::string explore_header`
📍 [tui.hpp:89](../../../../src/tui/tui.hpp#L89)
📍 [tui.hpp:90](../../../../src/tui/tui.hpp#L90)
### `int explore_focus_idx`
📍 [tui.hpp:90](../../../../src/tui/tui.hpp#L90)
📍 [tui.hpp:91](../../../../src/tui/tui.hpp#L91)
### `std::atomic< bool > loading`
📍 [tui.hpp:93](../../../../src/tui/tui.hpp#L93)
📍 [tui.hpp:94](../../../../src/tui/tui.hpp#L94)
true while a script is being processed; read by tick thread.
### `std::atomic< bool > tick_in_flight`
📍 [tui.hpp:94](../../../../src/tui/tui.hpp#L94)
📍 [tui.hpp:95](../../../../src/tui/tui.hpp#L95)
main thread acks each tick by clearing this; ticker waits.
### `std::string loading_filename`
📍 [tui.hpp:95](../../../../src/tui/tui.hpp#L95)
📍 [tui.hpp:96](../../../../src/tui/tui.hpp#L96)
### `std::vector< std::string > loading_lines`
📍 [tui.hpp:96](../../../../src/tui/tui.hpp#L96)
📍 [tui.hpp:97](../../../../src/tui/tui.hpp#L97)
### `size_t loading_idx`
📍 [tui.hpp:97](../../../../src/tui/tui.hpp#L97)
📍 [tui.hpp:98](../../../../src/tui/tui.hpp#L98)
### `int loading_executed`
📍 [tui.hpp:98](../../../../src/tui/tui.hpp#L98)
📍 [tui.hpp:99](../../../../src/tui/tui.hpp#L99)
### `int loading_lineno`
📍 [tui.hpp:99](../../../../src/tui/tui.hpp#L99)
📍 [tui.hpp:100](../../../../src/tui/tui.hpp#L100)
### `bool loading_prev_in_source`
📍 [tui.hpp:100](../../../../src/tui/tui.hpp#L100)
📍 [tui.hpp:101](../../../../src/tui/tui.hpp#L101)
### `ftxui::ScreenInteractive * screen_ptr`
📍 [tui.hpp:101](../../../../src/tui/tui.hpp#L101)
📍 [tui.hpp:102](../../../../src/tui/tui.hpp#L102)
set in `Run()` so Source() can post events. so Source() can post events.
### `std::vector< std::string > net_modules`
📍 [tui.hpp:104](../../../../src/tui/tui.hpp#L104)
📍 [tui.hpp:105](../../../../src/tui/tui.hpp#L105)
### `int net_module_idx`
📍 [tui.hpp:105](../../../../src/tui/tui.hpp#L105)
📍 [tui.hpp:106](../../../../src/tui/tui.hpp#L106)
### `std::string net_sig_filter`
📍 [tui.hpp:106](../../../../src/tui/tui.hpp#L106)
📍 [tui.hpp:107](../../../../src/tui/tui.hpp#L107)
### `std::vector< std::string > net_sigs`
📍 [tui.hpp:107](../../../../src/tui/tui.hpp#L107)
📍 [tui.hpp:108](../../../../src/tui/tui.hpp#L108)
rebuilt every frame from filter
### `int net_sig_idx`
📍 [tui.hpp:108](../../../../src/tui/tui.hpp#L108)
📍 [tui.hpp:109](../../../../src/tui/tui.hpp#L109)
### `int net_focus_idx`
📍 [tui.hpp:109](../../../../src/tui/tui.hpp#L109)
📍 [tui.hpp:110](../../../../src/tui/tui.hpp#L110)
### `std::vector< std::string > settype_modules`
📍 [tui.hpp:112](../../../../src/tui/tui.hpp#L112)
📍 [tui.hpp:113](../../../../src/tui/tui.hpp#L113)
### `int settype_m_idx`
📍 [tui.hpp:113](../../../../src/tui/tui.hpp#L113)
📍 [tui.hpp:114](../../../../src/tui/tui.hpp#L114)
### `std::string settype_p_filter`
📍 [tui.hpp:114](../../../../src/tui/tui.hpp#L114)
📍 [tui.hpp:115](../../../../src/tui/tui.hpp#L115)
### `std::vector< std::string > settype_p_list`
📍 [tui.hpp:115](../../../../src/tui/tui.hpp#L115)
📍 [tui.hpp:116](../../../../src/tui/tui.hpp#L116)
### `int settype_p_idx`
📍 [tui.hpp:116](../../../../src/tui/tui.hpp#L116)
📍 [tui.hpp:117](../../../../src/tui/tui.hpp#L117)
### `std::string settype_type`
📍 [tui.hpp:117](../../../../src/tui/tui.hpp#L117)
📍 [tui.hpp:118](../../../../src/tui/tui.hpp#L118)
### `std::string settype_status`
📍 [tui.hpp:118](../../../../src/tui/tui.hpp#L118)
📍 [tui.hpp:119](../../../../src/tui/tui.hpp#L119)
### `int settype_focus_idx`
📍 [tui.hpp:119](../../../../src/tui/tui.hpp#L119)
📍 [tui.hpp:120](../../../../src/tui/tui.hpp#L120)
## Public Functions
### `Tui()`
📍 [tui.hpp:122](../../../../src/tui/tui.hpp#L122)
📍 [tui.hpp:123](../../../../src/tui/tui.hpp#L123)
### `~Tui()`
📍 [tui.hpp:123](../../../../src/tui/tui.hpp#L123)
📍 [tui.hpp:124](../../../../src/tui/tui.hpp#L124)
### `void Run()`
📍 [tui.hpp:124](../../../../src/tui/tui.hpp#L124)
📍 [tui.hpp:125](../../../../src/tui/tui.hpp#L125)
### `void DumpCommandsMd(std::ostream &out) const`
📍 [tui.hpp:126](../../../../src/tui/tui.hpp#L126)
## Private Functions
### `void RegisterCommands()`
📍 [tui.hpp:128](../../../../src/tui/tui.hpp#L128)
📍 [tui.hpp:130](../../../../src/tui/tui.hpp#L130)
### `void Print(const std::string &line)`
📍 [tui.hpp:131](../../../../src/tui/tui.hpp#L131)
📍 [tui.hpp:133](../../../../src/tui/tui.hpp#L133)
### `void Submit()`
📍 [tui.hpp:132](../../../../src/tui/tui.hpp#L132)
📍 [tui.hpp:134](../../../../src/tui/tui.hpp#L134)
### `void Dispatch(const std::string &raw)`
📍 [tui.hpp:133](../../../../src/tui/tui.hpp#L133)
📍 [tui.hpp:135](../../../../src/tui/tui.hpp#L135)
### `void Finalize(const std::string &name, const CommandSpec &spec, const std::vector< std::string > &args)`
📍 [tui.hpp:134](../../../../src/tui/tui.hpp#L134)
📍 [tui.hpp:136](../../../../src/tui/tui.hpp#L136)
### `void HistoryUp()`
📍 [tui.hpp:137](../../../../src/tui/tui.hpp#L137)
📍 [tui.hpp:139](../../../../src/tui/tui.hpp#L139)
### `void HistoryDown()`
📍 [tui.hpp:138](../../../../src/tui/tui.hpp#L138)
📍 [tui.hpp:140](../../../../src/tui/tui.hpp#L140)
### `void CancelPending()`
📍 [tui.hpp:139](../../../../src/tui/tui.hpp#L139)
📍 [tui.hpp:141](../../../../src/tui/tui.hpp#L141)
### `void LoadHistory()`
📍 [tui.hpp:140](../../../../src/tui/tui.hpp#L140)
📍 [tui.hpp:142](../../../../src/tui/tui.hpp#L142)
### `void AppendHistory(const std::string &cmd)`
📍 [tui.hpp:141](../../../../src/tui/tui.hpp#L141)
📍 [tui.hpp:143](../../../../src/tui/tui.hpp#L143)
### `void Source(const std::string &filename)`
📍 [tui.hpp:142](../../../../src/tui/tui.hpp#L142)
📍 [tui.hpp:144](../../../../src/tui/tui.hpp#L144)
### `void ProcessNextSourceLine()`
📍 [tui.hpp:143](../../../../src/tui/tui.hpp#L143)
📍 [tui.hpp:145](../../../../src/tui/tui.hpp#L145)
### `std::string ExpandVars(const std::string &s) const`
📍 [tui.hpp:144](../../../../src/tui/tui.hpp#L144)
📍 [tui.hpp:146](../../../../src/tui/tui.hpp#L146)
### `void CompleteCommand(size_t start=0)`
📍 [tui.hpp:147](../../../../src/tui/tui.hpp#L147)
📍 [tui.hpp:149](../../../../src/tui/tui.hpp#L149)
### `void CompletePath(size_t start=0)`
📍 [tui.hpp:148](../../../../src/tui/tui.hpp#L148)
📍 [tui.hpp:150](../../../../src/tui/tui.hpp#L150)
### `void CompleteInline()`
📍 [tui.hpp:149](../../../../src/tui/tui.hpp#L149)
📍 [tui.hpp:151](../../../../src/tui/tui.hpp#L151)
### `void RefreshFilteredPartList(const std::vector< std::string > &modules, int m_idx, const std::string &filter, std::vector< std::string > &out, int &sel_idx)`
📍 [tui.hpp:152](../../../../src/tui/tui.hpp#L152)
📍 [tui.hpp:154](../../../../src/tui/tui.hpp#L154)
### `ftxui::Component BuildMainScreen(ftxui::ScreenInteractive &screen)`
📍 [tui.hpp:159](../../../../src/tui/tui.hpp#L159)
📍 [tui.hpp:161](../../../../src/tui/tui.hpp#L161)
### `ftxui::Component BuildSearchScreen()`
📍 [tui.hpp:160](../../../../src/tui/tui.hpp#L160)
📍 [tui.hpp:162](../../../../src/tui/tui.hpp#L162)
### `ftxui::Component BuildConnectScreen()`
📍 [tui.hpp:161](../../../../src/tui/tui.hpp#L161)
📍 [tui.hpp:163](../../../../src/tui/tui.hpp#L163)
### `ftxui::Component BuildSettypeScreen()`
📍 [tui.hpp:162](../../../../src/tui/tui.hpp#L162)
📍 [tui.hpp:164](../../../../src/tui/tui.hpp#L164)
### `ftxui::Component BuildExploreScreen()`
📍 [tui.hpp:163](../../../../src/tui/tui.hpp#L163)
📍 [tui.hpp:165](../../../../src/tui/tui.hpp#L165)
### `ftxui::Component BuildNetScreen()`
📍 [tui.hpp:164](../../../../src/tui/tui.hpp#L164)
📍 [tui.hpp:166](../../../../src/tui/tui.hpp#L166)
---