François
043fef0a31
- `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>
82 lines
3.1 KiB
Markdown
82 lines
3.1 KiB
Markdown
# essim documentation
|
|
|
|
Auto-generated API reference and high-level design notes for the
|
|
[essim](../README.md) system digital twin.
|
|
|
|
## Layout
|
|
|
|
- [`user/`](user/) — **user-facing** docs (hand-written intro/tutorial
|
|
+ auto-generated command reference). Start at [`user/index.md`](user/index.md).
|
|
- [`api/`](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`](api/index.md).
|
|
- [`../DESIGN.md`](../DESIGN.md) — implementation notes: domain
|
|
conventions, TUI flow, gotchas. Hand-maintained.
|
|
- [`classes.puml`](classes.puml) — PlantUML class diagram for the
|
|
domain model. Render with `plantuml classes.puml` for a PNG/SVG.
|
|
- [`Doxyfile.in`](Doxyfile.in) / [`gen_api_md.py`](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:
|
|
|
|
```sh
|
|
# 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.
|