François
7d307dad57
New user-facing features:
- `export connections <file>` writes a tabular dump of every wire pair:
connection, transform, left/right module/part/pin/signal/type/suspect,
mixed-types flag. Dispatch on extension: `.csv` (flat file) or `.ods`
(one sheet per connection). Any other extension shows an error and
writes nothing.
- Bare `export` (or dashboard `[x]`, or palette `export`) opens an
interactive file-picker dialog with a CSV/ODS toggle at the top.
Picking a filter rewrites the filename's extension. Last-used
directory and filename are remembered per-call-site.
- Two new CLI flags on the binary: `--source FILE` to run a script at
boot, `--restore FILE` to restore a snapshot at boot. Combinable.
Reusable infrastructure:
- `OdsWriter` (`src/imports/ods_writer.{hpp,cpp}`): minimal .ods writer
using libzip + pugixml (already in the build for the importer).
Multi-sheet workbook of string cells. ~180 lines, no new dep.
- Generic file-picker dialog (`screen_filedialog.cpp`): one Modal
reused for any "pick a path" interaction via
`OpenFileDialog(title, persist_key, default_filename, filters, cb)`.
Validates the picked extension against the filter whitelist;
unknown ones stay in the dialog with a status message. Persists
(dir, filename) per `persist_key`.
- Generic error modal (`screen_error.cpp`, `ShowError(msg)`): centred
red-titled popup, dismissable with Esc/Enter. Used by the export
failures (open-for-write, ODS save, unknown extension/kind);
ready for adoption elsewhere.
- Per-key path persistence (`SaveLastUsed`/`LoadLastUsed` in
`shell.cpp`): two-line file per key under the user-data dir.
- `UserDataDir()` extracted from the history path helper so the new
per-key persistence shares the same XDG/AppData logic.
- New help-screen topic "Export"; user-facing `doc/user/analysis.md`
gains an "Exporting" section; `DESIGN.md` gains a generics
section covering the dialog / error modal / persistence / ODS
writer; `DumpCommandsMd` now respects the `hidden` flag (the
`connect` alias no longer appears in the auto-gen reference).
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
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.
- auto-generated command reference). Start at
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 withplantuml classes.pumlfor 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
doxybook2is not packaged in Arch / AUR and gets stale upstream.moxygendrags 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.@throwsfor 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.