electronics/essim
1
0
Fork 0
Code Issues 3 Pull Requests Packages Releases Wiki Activity

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

Browse Source 
- `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:
Foué
2026-05-12 08:29:45 +02:00
parent 66460262af
commit 043fef0a31
16 changed files with 825 additions and 242 deletions
Download Patch File Download Diff File Expand all files Collapse all files

9
DESIGN.md
View File

@@ -167,14 +167,17 @@ Each successful submission appends a single line to the file (so a crash doesn't
## Documentation
`doc/` hosts:
- `api/` — auto-generated Markdown API reference, browseable directly in gitea.
- `api/` — auto-generated Markdown C++ API reference (developer-facing).
- `user/` — hand-written intro + auto-generated command reference (user-facing).
- `Doxyfile.in` — CMake-templated Doxygen config (XML-only output to `build/doc/xml/`).
- `gen_api_md.py` — custom XML → Markdown emitter (~330 lines, stdlib-only Python).
- `README.md`, `classes.puml` — meta + diagram.
Pipeline: `doxygen` extracts the XML from `src/**`, then `gen_api_md.py` walks `index.xml` plus each `class*.xml` / `*_8hpp.xml` and emits one Markdown file per class/struct/file plus an index. Source-code references use relative paths (`../../../../src/...#L42`) so gitea's renderer turns them into clickable line-anchored links. We picked a custom emitter over `doxybook2` (not in Arch/AUR) and `moxygen` (Node dep) to keep the toolchain pure-C++/Python and trivially modifiable.
**API reference pipeline**: `doxygen` extracts the XML from `src/**`, then `gen_api_md.py` walks `index.xml` plus each `class*.xml` / `*_8hpp.xml` and emits one Markdown file per class/struct/file plus an index. Source-code references use relative paths (`../../../../src/...#L42`) so gitea's renderer turns them into clickable line-anchored links. Chosen over `doxybook2` (not in Arch/AUR) and `moxygen` (Node dep) to keep the toolchain pure-C++/Python and trivially modifiable.
Regenerate with `cmake --build build --target doc` after substantive code changes — the target is auto-created when both Doxygen and Python 3 are present at configure time; otherwise the regular build target is unaffected and a status line records which tool is missing. The Markdown output is committed (`doc/api/`), so gitea readers see fresh docs without building.
**Command reference pipeline**: `essim --commands-md <out>` instantiates a `Tui` (which calls `RegisterCommands()`), then `Tui::DumpCommandsMd(ostream&)` iterates the `commands` map and writes Markdown — two groups (interactive / other), each command with description, numbered arguments, completion mode per arg, scriptability/interactivity notes. The binary is the single source of truth, so a new `CommandSpec` field is reflected in the doc as soon as `DumpCommandsMd` is taught to render it (no separate parser to drift). The `doc` target `DEPENDS essim` so a stale binary is rebuilt automatically.
`doc/user/index.md` and `doc/user/scripting.md` are hand-written (tutorial + scripting semantics); only `doc/user/commands.md` is regenerated. Regenerate everything with `cmake --build build --target doc` — the target is auto-created when both Doxygen and Python 3 are present at configure time; otherwise the regular build target is unaffected and a status line records which tool is missing. The Markdown output is committed (`doc/api/`, `doc/user/commands.md`) so gitea readers see fresh docs without building.
## Memory layout for sessions