Files

François 043fef0a31 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>

2026-05-12 08:29:45 +02:00

3.1 KiB

Raw Blame History

essim documentation

Auto-generated API reference and high-level design notes for the essim system digital twin.

Layout

user/ — user-facing docs (hand-written intro/tutorial
- auto-generated command reference). Start at user/index.md.
api/ — developer-facing API reference (Doxygen XML → custom Markdown emitter). Browse classes and files directly in gitea's Markdown renderer. Top page: api/index.md.
../DESIGN.md — implementation notes: domain conventions, TUI flow, gotchas. Hand-maintained.
classes.puml — PlantUML class diagram for the domain model. Render with plantuml classes.puml for a PNG/SVG.
Doxyfile.in / gen_api_md.py — the toolchain (templated Doxygen config + custom XML→Markdown emitter).

Regenerating the API reference

The Markdown tree under doc/api/ is committed so it's readable directly on gitea. After substantive code changes, regenerate it:

# 1. Tooling (once): Doxygen, plus a Python 3 interpreter (already on Arch).
pacman -S doxygen

# 2. Configure once (or after editing doc/Doxyfile.in):
cmake -S . -B build

# 3. Regenerate:
cmake --build build --target doc

# 4. Review and commit the updated doc/api/ tree:
git add doc/api/
git status doc/api/

Pipeline:

src/**/*.{hpp,cpp}  ──┐
README.md            ─┼─► doxygen ─► build/doc/xml/  ─► gen_api_md.py ─► doc/api/
DESIGN.md            ─┘            (Doxyfile.in)

(built essim) ────────► essim --commands-md ──────────────────────────► doc/user/commands.md

doc/user/index.md and doc/user/scripting.md are hand-written; only doc/user/commands.md is regenerated. The doc target depends on the essim binary so a stale build is rebuilt before the dump is taken.

If either Doxygen or Python 3 is missing at CMake-configure time the doc target is silently disabled (the regular build still works) and a status line is emitted in the CMake log telling you which one to install.

Why a custom emitter rather than `doxybook2` / `moxygen`

doxybook2 is not packaged in Arch / AUR and gets stale upstream.
moxygen drags Node into a pure-C++ project.
The emitter is one Python file (gen_api_md.py, ~330 lines) with zero external dependencies — easy to read, easy to tweak, robust to Doxygen version changes (the XML schema is stable).

Tailor the output by editing gen_api_md.py directly: add columns to the class table, change the source-link format, group sections differently, etc.

Comment style

The codebase uses standard Doxygen markers:

/// for single-line briefs.
/** … */ for multi-line blocks.
@param, @return, @brief (or @short) tags inside blocks.
@throws for exceptions a function may raise.

JAVADOC_AUTOBRIEF = YES is set so the first sentence of a multi-line comment counts as the brief description without needing an explicit @brief tag.

3.1 KiB Raw Blame History