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

Auto-generated API doc: doxygen → custom Python emitter → doc/api/.

Browse Source 
`cmake --build build --target doc` runs Doxygen to produce XML, then
`doc/gen_api_md.py` (~330 lines, stdlib-only) emits a Markdown tree
under `doc/api/` that gitea renders directly in its file browser.

- 24 class/struct pages + 51 source-file pages + indices, with source
  links of the form `../../../../src/...#L42` that gitea turns into
  clickable line-anchored links.
- Doxyfile.in templated by CMake (XML-only output to build/doc/xml/).
- Pure Python emitter, zero external deps — no doxybook2 (not packaged
  on Arch) and no moxygen (avoids Node).
- Target gracefully disabled if Doxygen or Python 3 is missing at
  configure time; regular build target unaffected.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
Foué
2026-05-12 08:13:15 +02:00
parent fe2dc13c89
commit 66460262af
83 changed files with 2845 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

55
doc/Doxyfile.in Normal file
View File

@@ -0,0 +1,55 @@
# Doxygen configuration for essim — produces XML only, consumed by
# doxybook2 to generate the Markdown tree under doc/api/.
# Substituted by CMake (`configure_file ... @ONLY`).
PROJECT_NAME = "@PROJECT_NAME@"
PROJECT_NUMBER = "@PROJECT_VERSION@"
PROJECT_BRIEF = "@PROJECT_DESCRIPTION@"
OUTPUT_DIRECTORY = @DOXYGEN_OUTPUT_DIR@
INPUT = @CMAKE_SOURCE_DIR@/src
RECURSIVE = YES
FILE_PATTERNS = *.hpp *.cpp *.h
EXCLUDE_PATTERNS = */build/* */build/_deps/*
# We only need XML; doxybook2 will turn that into Markdown.
GENERATE_HTML = NO
GENERATE_LATEX = NO
GENERATE_XML = YES
XML_OUTPUT = xml
XML_PROGRAMLISTING = NO
# Extraction policy — include everything the user can usefully reach, but
# keep private implementation details out by default.
EXTRACT_ALL = YES
EXTRACT_PRIVATE = NO
EXTRACT_STATIC = YES
EXTRACT_LOCAL_CLASSES = YES
EXTRACT_ANON_NSPACES = NO
# Comment style — the existing code uses Doxygen-flavoured `///` and
# `/** … */`, both of which Doxygen recognises by default. JAVADOC_AUTOBRIEF
# lets a single-line comment serve as the brief description.
JAVADOC_AUTOBRIEF = YES
QT_AUTOBRIEF = YES
MULTILINE_CPP_IS_BRIEF = YES
# Preprocess macros (forward declarations, #pragma once, etc.).
ENABLE_PREPROCESSING = YES
MACRO_EXPANSION = NO
# Warnings — be helpful but not noisy.
QUIET = YES
WARN_IF_UNDOCUMENTED = NO
WARN_IF_DOC_ERROR = YES
WARN_NO_PARAMDOC = NO
# Diagrams — Graphviz isn't needed for Markdown output; doxybook2 ignores
# image references unless explicitly handled. Keep DOT off so the build
# stays light.
HAVE_DOT = NO
# Mainpage — link the top-level README so doxybook2 picks it up as the
# landing page in doc/api/.
USE_MDFILE_AS_MAINPAGE = @CMAKE_SOURCE_DIR@/README.md
INPUT += @CMAKE_SOURCE_DIR@/README.md @CMAKE_SOURCE_DIR@/DESIGN.md

73
doc/README.md Normal file
View File

@@ -0,0 +1,73 @@
# essim documentation
Auto-generated API reference and high-level design notes for the
[essim](../README.md) system digital twin.
## Layout
- [`api/`](api/) — auto-generated 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)
```
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.

45
doc/api/classes/Connection.md Normal file
View File

@@ -0,0 +1,45 @@
# Connection
`class Connection` — inherits [SystemElement](../classes/SystemElement.md)
Defined in [connect.hpp:13](../../../../src/system/connect.hpp#L13)
## Public Attributes
### `Module * m1`
📍 [connect.hpp:16](../../../../src/system/connect.hpp#L16)
### `Part * p1`
📍 [connect.hpp:17](../../../../src/system/connect.hpp#L17)
### `Module * m2`
📍 [connect.hpp:18](../../../../src/system/connect.hpp#L18)
### `Part * p2`
📍 [connect.hpp:19](../../../../src/system/connect.hpp#L19)
### `std::string transform_name`
📍 [connect.hpp:20](../../../../src/system/connect.hpp#L20)
### `std::vector< std::pair< Pin *, Pin * > > pin_map`
📍 [connect.hpp:21](../../../../src/system/connect.hpp#L21)
## Public Functions
### `Connection(std::string name)`
📍 [connect.hpp:23](../../../../src/system/connect.hpp#L23)
### `Connection(std::string name, Module *m1, Part *p1, Module *m2, Part *p2)`
📍 [connect.hpp:24](../../../../src/system/connect.hpp#L24)
---
← [Back to classes](index.md) · [Top](../index.md)

19
doc/api/classes/Connections.md Normal file
View File

@@ -0,0 +1,19 @@
# Connections
`class Connections` — inherits [SystemElementContainer< Connection >](../classes/SystemElementContainer.md)
Defined in [connect.hpp:27](../../../../src/system/connect.hpp#L27)
## Public Functions
### `Connections(void)`
📍 [connect.hpp:30](../../../../src/system/connect.hpp#L30)
### `Connections(std::vector< Connection * > connections)`
📍 [connect.hpp:31](../../../../src/system/connect.hpp#L31)
---
← [Back to classes](index.md) · [Top](../index.md)

19
doc/api/classes/IdentityTransform.md Normal file
View File

@@ -0,0 +1,19 @@
# IdentityTransform
`class IdentityTransform` — inherits [Transform](../classes/Transform.md)
Defined in [transform.hpp:42](../../../../src/system/transform.hpp#L42)
## Public Functions
### `IdentityTransform()`
📍 [transform.hpp:45](../../../../src/system/transform.hpp#L45)
### `std::vector< std::pair< Pin *, Pin * > > apply(Part *a, Part *b) const override`
📍 [transform.hpp:46](../../../../src/system/transform.hpp#L46)
---
← [Back to classes](index.md) · [Top](../index.md)

27
doc/api/classes/ImportAltium.md Normal file
View File

@@ -0,0 +1,27 @@
# ImportAltium
`class ImportAltium` — inherits [ImportBase](../classes/ImportBase.md)
Defined in [import_altium.hpp:8](../../../../src/imports/import_altium.hpp#L8)
## Public Functions
### `ImportAltium(std::string filename)`
📍 [import_altium.hpp:10](../../../../src/imports/import_altium.hpp#L10)
### `void parse(Signals *signals) override`
📍 [import_altium.hpp:11](../../../../src/imports/import_altium.hpp#L11)
Pure virtual method for parsing the file.
Derived classes must implement this method to define how the file is parsed.
**Parameters**
- `signals` — Pointer to the signals object to be completed.
---
← [Back to classes](index.md) · [Top](../index.md)

69
doc/api/classes/ImportBase.md Normal file
View File

@@ -0,0 +1,69 @@
# ImportBase
`class ImportBase`
Defined in [import_base.hpp:16](../../../../src/imports/import_base.hpp#L16)
Base class for importing data from a file.
This class provides a foundation for parsing files and managing system parts and signals. Derived classes must implement the ``parse`` method. method.
## Protected Attributes
### `Parts * prts`
📍 [import_base.hpp:19](../../../../src/imports/import_base.hpp#L19)
Pointer to the [Parts](../classes/Parts.md) object. object.
### `std::fstream file_lines`
📍 [import_base.hpp:20](../../../../src/imports/import_base.hpp#L20)
File stream for reading the input file.
## Public Functions
### `ImportBase(std::string file_name)`
📍 [import_base.hpp:30](../../../../src/imports/import_base.hpp#L30)
Constructor for [ImportBase](../classes/ImportBase.md)..
Initializes the file stream and creates new [Parts](../classes/Parts.md) and and [Signals](../classes/Signals.md) objects. objects.
**Parameters**
- `file_name` — Name of the file to be imported.
### `void parse(Signals *signals)=0`
📍 [import_base.hpp:42](../../../../src/imports/import_base.hpp#L42)
Pure virtual method for parsing the file.
Derived classes must implement this method to define how the file is parsed.
**Parameters**
- `signals` — Pointer to the signals object to be completed.
### `Parts * parts()`
📍 [import_base.hpp:48](../../../../src/imports/import_base.hpp#L48)
Retrieves the [Parts](../classes/Parts.md) object. object.
**Returns** Pointer to the [Parts](../classes/Parts.md) object.
### `~ImportBase()=default`
📍 [import_base.hpp:58](../../../../src/imports/import_base.hpp#L58)
Virtual destructor for [ImportBase](../classes/ImportBase.md)..
Ensures proper cleanup of derived classes.
---
← [Back to classes](index.md) · [Top](../index.md)

43
doc/api/classes/ImportMentor.md Normal file
View File

@@ -0,0 +1,43 @@
# ImportMentor
`class ImportMentor` — inherits [ImportBase](../classes/ImportBase.md)
Defined in [import_mentor.hpp:8](../../../../src/imports/import_mentor.hpp#L8)
## Public Functions
### `ImportMentor(std::string filename)`
📍 [import_mentor.hpp:11](../../../../src/imports/import_mentor.hpp#L11)
Constructor for [ImportMentor](../classes/ImportMentor.md)..
Initializes the base class with the provided filename.
**Parameters**
- `filename` — Name of the file to be imported.
### `void parse(Signals *signals) override`
📍 [import_mentor.hpp:12](../../../../src/imports/import_mentor.hpp#L12)
Parses the file to extract parts, pins, and signals.
This method reads the file line by line, identifies parts and pins using regular expressions, and associates them with signals.
**Parameters**
- `signals` — Pointer to the [Signals](../classes/Signals.md) object used for managing signal connections.
### `~ImportMentor()`
📍 [import_mentor.hpp:13](../../../../src/imports/import_mentor.hpp#L13)
Destructor for [ImportMentor](../classes/ImportMentor.md)..
Ensures proper cleanup by calling the base class destructor.
---
← [Back to classes](index.md) · [Top](../index.md)

33
doc/api/classes/ImportOds.md Normal file
View File

@@ -0,0 +1,33 @@
# ImportOds
`class ImportOds` — inherits [ImportBase](../classes/ImportBase.md)
Defined in [import_ods.hpp:6](../../../../src/imports/import_ods.hpp#L6)
## Private Attributes
### `std::string filename_`
📍 [import_ods.hpp:8](../../../../src/imports/import_ods.hpp#L8)
## Public Functions
### `ImportOds(std::string filename)`
📍 [import_ods.hpp:11](../../../../src/imports/import_ods.hpp#L11)
### `void parse(Signals *signals) override`
📍 [import_ods.hpp:12](../../../../src/imports/import_ods.hpp#L12)
Pure virtual method for parsing the file.
Derived classes must implement this method to define how the file is parsed.
**Parameters**
- `signals` — Pointer to the signals object to be completed.
---
← [Back to classes](index.md) · [Top](../index.md)

35
doc/api/classes/Module.md Normal file
View File

@@ -0,0 +1,35 @@
# Module
`class Module` — inherits [SystemElementContainer< Part >](../classes/SystemElementContainer.md)
Defined in [modules.hpp:12](../../../../src/system/modules.hpp#L12)
Forward declaration of the [Signals](../classes/Signals.md) class. class.
## Public Attributes
### `Signals * signals`
📍 [modules.hpp:15](../../../../src/system/modules.hpp#L15)
### `Modules * prnt`
📍 [modules.hpp:16](../../../../src/system/modules.hpp#L16)
## Public Functions
### `Module(std::string name)`
📍 [modules.hpp:17](../../../../src/system/modules.hpp#L17)
### `~Module()`
📍 [modules.hpp:18](../../../../src/system/modules.hpp#L18)
### `void add(Part *part) override`
📍 [modules.hpp:20](../../../../src/system/modules.hpp#L20)
---
← [Back to classes](index.md) · [Top](../index.md)

27
doc/api/classes/Modules.md Normal file
View File

@@ -0,0 +1,27 @@
# Modules
`class Modules` — inherits [SystemElementContainer< Module >](../classes/SystemElementContainer.md)
Defined in [modules.hpp:23](../../../../src/system/modules.hpp#L23)
## Public Functions
### `Modules(void)`
📍 [modules.hpp:26](../../../../src/system/modules.hpp#L26)
### `Modules(std::vector< Module * > parts)`
📍 [modules.hpp:27](../../../../src/system/modules.hpp#L27)
### `void add(Module *module)`
📍 [modules.hpp:28](../../../../src/system/modules.hpp#L28)
### `~Modules()`
📍 [modules.hpp:29](../../../../src/system/modules.hpp#L29)
---
← [Back to classes](index.md) · [Top](../index.md)

15
doc/api/classes/Net.md Normal file
View File

@@ -0,0 +1,15 @@
# Net
`struct Net`
Defined in [nets.hpp:16](../../../../src/system/nets.hpp#L16)
## Public Attributes
### `std::vector< std::pair< Module *, Signal * > > members`
📍 [nets.hpp:17](../../../../src/system/nets.hpp#L17)
---
← [Back to classes](index.md) · [Top](../index.md)

45
doc/api/classes/Part.md Normal file
View File

@@ -0,0 +1,45 @@
# Part
`class Part` — inherits [SystemElementContainer< Pin >](../classes/SystemElementContainer.md)
Defined in [parts.hpp:11](../../../../src/system/parts.hpp#L11)
Forward declaration of the [Module](../classes/Module.md) class. class.
## Public Attributes
### `Module * prnt`
📍 [parts.hpp:16](../../../../src/system/parts.hpp#L16)
Pointer to the parent module.
### `std::string connector_type`
📍 [parts.hpp:17](../../../../src/system/parts.hpp#L17)
Tag used by the transform registry; empty = untyped.
### `ComponentKind kind`
📍 [parts.hpp:18](../../../../src/system/parts.hpp#L18)
Inferred from the part name's reference-designator prefix.
## Public Functions
### `Part(std::string name)`
📍 [parts.hpp:14](../../../../src/system/parts.hpp#L14)
### `~Part()`
📍 [parts.hpp:15](../../../../src/system/parts.hpp#L15)
### `void add(Pin *pin) override`
📍 [parts.hpp:19](../../../../src/system/parts.hpp#L19)
---
← [Back to classes](index.md) · [Top](../index.md)

19
doc/api/classes/Parts.md Normal file
View File

@@ -0,0 +1,19 @@
# Parts
`class Parts` — inherits [SystemElementContainer< Part >](../classes/SystemElementContainer.md)
Defined in [parts.hpp:22](../../../../src/system/parts.hpp#L22)
## Public Functions
### `Parts(void)`
📍 [parts.hpp:25](../../../../src/system/parts.hpp#L25)
### `Parts(std::vector< Part * > parts)`
📍 [parts.hpp:26](../../../../src/system/parts.hpp#L26)
---
← [Back to classes](index.md) · [Top](../index.md)

31
doc/api/classes/Signal.md Normal file
View File

@@ -0,0 +1,31 @@
# Signal
`class Signal` — inherits [SystemElementContainer< Pin >](../classes/SystemElementContainer.md)
Defined in [signals.hpp:11](../../../../src/system/signals.hpp#L11)
## Public Attributes
### `Signals * prnt`
📍 [signals.hpp:14](../../../../src/system/signals.hpp#L14)
Pointer to the parent signals object.
### `SignalType type`
📍 [signals.hpp:15](../../../../src/system/signals.hpp#L15)
## Public Functions
### `Signal(std::string name)`
📍 [signals.hpp:16](../../../../src/system/signals.hpp#L16)
### `void add(Pin *pin) override`
📍 [signals.hpp:17](../../../../src/system/signals.hpp#L17)
---
← [Back to classes](index.md) · [Top](../index.md)

27
doc/api/classes/Signals.md Normal file
View File

@@ -0,0 +1,27 @@
# Signals
`class Signals` — inherits [SystemElementContainer< Signal >](../classes/SystemElementContainer.md)
Defined in [signals.hpp:20](../../../../src/system/signals.hpp#L20)
## Public Functions
### `Signals(void)`
📍 [signals.hpp:23](../../../../src/system/signals.hpp#L23)
### `Signals(std::vector< Signal * > signals)`
📍 [signals.hpp:24](../../../../src/system/signals.hpp#L24)
### `void add(Signal *signal) override`
📍 [signals.hpp:25](../../../../src/system/signals.hpp#L25)
### `~Signals()`
📍 [signals.hpp:26](../../../../src/system/signals.hpp#L26)
---
← [Back to classes](index.md) · [Top](../index.md)

41
doc/api/classes/System.md Normal file
View File

@@ -0,0 +1,41 @@
# System
`class System`
Defined in [system.hpp:17](../../../../src/system/system.hpp#L17)
## Private Attributes
### `Modules * mods`
📍 [system.hpp:19](../../../../src/system/system.hpp#L19)
### `Connections * conns`
📍 [system.hpp:20](../../../../src/system/system.hpp#L20)
## Public Functions
### `System()`
📍 [system.hpp:23](../../../../src/system/system.hpp#L23)
### `void Load(std::string module_name, std::string filename, ImportType type)`
📍 [system.hpp:24](../../../../src/system/system.hpp#L24)
### `Modules * modules() const`
📍 [system.hpp:25](../../../../src/system/system.hpp#L25)
### `Connections * connections() const`
📍 [system.hpp:26](../../../../src/system/system.hpp#L26)
### `~System()`
📍 [system.hpp:27](../../../../src/system/system.hpp#L27)
---
← [Back to classes](index.md) · [Top](../index.md)

29
doc/api/classes/SystemElement.md Normal file
View File

@@ -0,0 +1,29 @@
# SystemElement
`class SystemElement`
Defined in [syselmts.hpp:14](../../../../src/system/syselmts.hpp#L14)
Represents a basic system element with a name.
## Public Attributes
### `string name`
📍 [syselmts.hpp:17](../../../../src/system/syselmts.hpp#L17)
## Public Functions
### `SystemElement(string name)`
📍 [syselmts.hpp:23](../../../../src/system/syselmts.hpp#L23)
Constructor for [SystemElement](../classes/SystemElement.md)..
**Parameters**
- `` — Name of the element.
---
← [Back to classes](index.md) · [Top](../index.md)

195
doc/api/classes/SystemElementContainer.md Normal file
View File

@@ -0,0 +1,195 @@
# SystemElementContainer
`class SystemElementContainer` — inherits [SystemElement](../classes/SystemElement.md)
Defined in [syselmts.hpp:32](../../../../src/system/syselmts.hpp#L32)
A container for managing system elements of type T.
## Public Types
### `using SystemElementContainer< T >::MapType = unordered_map<string, T *>`
📍 [syselmts.hpp:35](../../../../src/system/syselmts.hpp#L35)
### `using SystemElementContainer< T >::iterator = typename MapType::iterator`
📍 [syselmts.hpp:36](../../../../src/system/syselmts.hpp#L36)
### `using SystemElementContainer< T >::const_iterator = typename MapType::const_iterator`
📍 [syselmts.hpp:37](../../../../src/system/syselmts.hpp#L37)
## Protected Attributes
### `unsigned int iter_count`
📍 [syselmts.hpp:40](../../../../src/system/syselmts.hpp#L40)
### `MapType content`
📍 [syselmts.hpp:41](../../../../src/system/syselmts.hpp#L41)
## Protected Functions
### `void add(MapType el_content)`
📍 [syselmts.hpp:47](../../../../src/system/syselmts.hpp#L47)
Adds elements from a map to the container.
**Parameters**
- `el_content` — Map of elements to add.
## Public Functions
### `SystemElementContainer(string name)`
📍 [syselmts.hpp:60](../../../../src/system/syselmts.hpp#L60)
Constructor for an empty container.
**Parameters**
- `` — Name of the container.
### `SystemElementContainer(string name, vector< T * > elements)`
📍 [syselmts.hpp:67](../../../../src/system/syselmts.hpp#L67)
Constructor with initial elements.
**Parameters**
- `` — Name of the container.
- `elements` — Vector of elements to add.
### `void add(string name, T *element)`
📍 [syselmts.hpp:78](../../../../src/system/syselmts.hpp#L78)
Adds a single element to the container with a given name.
**Parameters**
- `` — Name of the element to add.
- `element` — Pointer to the element to add.
**Throws**
- `runtime_error` — If the element's name is empty or already exists.
### `void add(T *element)`
📍 [syselmts.hpp:96](../../../../src/system/syselmts.hpp#L96)
Adds a single element to the container.
**Parameters**
- `element` — Pointer to the element to add.
**Throws**
- `runtime_error` — If the element's name is empty or already exists.
### `bool exists(string name)`
📍 [syselmts.hpp:106](../../../../src/system/syselmts.hpp#L106)
Checks if an element exists in the container.
**Parameters**
- `` — Name of the element to check.
**Returns** True if the element exists, false otherwise.
### `void add(SystemElementContainer< T > *elements)`
📍 [syselmts.hpp:123](../../../../src/system/syselmts.hpp#L123)
Adds elements from another container.
**Parameters**
- `elements` — Pointer to another container.
### `void add(vector< T * > elements)`
📍 [syselmts.hpp:132](../../../../src/system/syselmts.hpp#L132)
Adds multiple elements from a vector.
**Parameters**
- `elements` — Vector of elements to add.
### `T * get(string name)`
📍 [syselmts.hpp:146](../../../../src/system/syselmts.hpp#L146)
Retrieves an element by its name.
**Parameters**
- `` — Name of the element to retrieve.
**Returns** Pointer to the element.
**Throws**
- `runtime_error` — If the element is not found.
### `T * merge(string name)`
📍 [syselmts.hpp:164](../../../../src/system/syselmts.hpp#L164)
Merges an element by retrieving it or creating a new one if it doesn't exist.
**Parameters**
- `` — Name of the element.
**Returns** Pointer to the merged or newly created element.
### `size_t size() const`
📍 [syselmts.hpp:178](../../../../src/system/syselmts.hpp#L178)
### `iterator begin()`
📍 [syselmts.hpp:184](../../../../src/system/syselmts.hpp#L184)
Returns an iterator to the beginning of the container.
**Returns** Iterator to the beginning.
### `iterator end()`
📍 [syselmts.hpp:190](../../../../src/system/syselmts.hpp#L190)
Returns an iterator to the end of the container.
**Returns** Iterator to the end.
### `const_iterator begin() const`
📍 [syselmts.hpp:196](../../../../src/system/syselmts.hpp#L196)
Returns a constant iterator to the beginning of the container.
**Returns** Constant iterator to the beginning.
### `const_iterator end() const`
📍 [syselmts.hpp:202](../../../../src/system/syselmts.hpp#L202)
Returns a constant iterator to the end of the container.
**Returns** Constant iterator to the end.
---
← [Back to classes](index.md) · [Top](../index.md)

29
doc/api/classes/Transform.md Normal file
View File

@@ -0,0 +1,29 @@
# Transform
`class Transform`
Defined in [transform.hpp:31](../../../../src/system/transform.hpp#L31)
## Public Attributes
### `std::string name`
📍 [transform.hpp:34](../../../../src/system/transform.hpp#L34)
## Public Functions
### `Transform(std::string name)`
📍 [transform.hpp:35](../../../../src/system/transform.hpp#L35)
### `~Transform()=default`
📍 [transform.hpp:36](../../../../src/system/transform.hpp#L36)
### `std::vector< std::pair< Pin *, Pin * > > apply(Part *a, Part *b) const =0`
📍 [transform.hpp:37](../../../../src/system/transform.hpp#L37)
---
← [Back to classes](index.md) · [Top](../index.md)

57
doc/api/classes/TransformRegistry.md Normal file
View File

@@ -0,0 +1,57 @@
# TransformRegistry
`class TransformRegistry`
Defined in [transform.hpp:49](../../../../src/system/transform.hpp#L49)
## Private Attributes
### `std::map< std::pair< std::string, std::string >, Transform * > entries`
📍 [transform.hpp:51](../../../../src/system/transform.hpp#L51)
### `Transform * identity_`
📍 [transform.hpp:52](../../../../src/system/transform.hpp#L52)
## Private Functions
### `TransformRegistry()`
📍 [transform.hpp:53](../../../../src/system/transform.hpp#L53)
### `~TransformRegistry()`
📍 [transform.hpp:54](../../../../src/system/transform.hpp#L54)
## Public Static Functions
### `TransformRegistry & get()`
📍 [transform.hpp:57](../../../../src/system/transform.hpp#L57)
## Public Functions
### `void add(const std::string &kindA, const std::string &kindB, Transform *t)`
📍 [transform.hpp:58](../../../../src/system/transform.hpp#L58)
### `Transform * lookup(const std::string &kindA, const std::string &kindB) const`
📍 [transform.hpp:61](../../../../src/system/transform.hpp#L61)
### `Transform * identity() const`
📍 [transform.hpp:62](../../../../src/system/transform.hpp#L62)
### `TransformRegistry(const TransformRegistry &)=delete`
📍 [transform.hpp:64](../../../../src/system/transform.hpp#L64)
### `TransformRegistry & operator=(const TransformRegistry &)=delete`
📍 [transform.hpp:65](../../../../src/system/transform.hpp#L65)
---
← [Back to classes](index.md) · [Top](../index.md)

397
doc/api/classes/Tui.md Normal file
View File

@@ -0,0 +1,397 @@
# Tui
`class Tui`
Defined in [tui.hpp:17](../../../../src/tui/tui.hpp#L17)
## Private type
### `enum Completion`
📍 [tui.hpp:18](../../../../src/tui/tui.hpp#L18)
## Private Attributes
### `std::vector< std::string > history`
📍 [tui.hpp:40](../../../../src/tui/tui.hpp#L40)
### `std::vector< std::string > recorded`
📍 [tui.hpp:41](../../../../src/tui/tui.hpp#L41)
### `std::vector< std::string > output`
📍 [tui.hpp:42](../../../../src/tui/tui.hpp#L42)
### `std::string input`
📍 [tui.hpp:43](../../../../src/tui/tui.hpp#L43)
### `int cursor_pos`
📍 [tui.hpp:44](../../../../src/tui/tui.hpp#L44)
### `int history_idx`
📍 [tui.hpp:45](../../../../src/tui/tui.hpp#L45)
### `int scroll_offset`
📍 [tui.hpp:46](../../../../src/tui/tui.hpp#L46)
Lines scrolled up from the tail; 0 = follow newest output.
### `bool quit`
📍 [tui.hpp:47](../../../../src/tui/tui.hpp#L47)
### `bool in_source`
📍 [tui.hpp:48](../../../../src/tui/tui.hpp#L48)
### `std::unique_ptr< System > sys`
📍 [tui.hpp:50](../../../../src/tui/tui.hpp#L50)
### `std::deque< Prompt > pending`
📍 [tui.hpp:51](../../../../src/tui/tui.hpp#L51)
### `std::map< std::string, CommandSpec > commands`
📍 [tui.hpp:52](../../../../src/tui/tui.hpp#L52)
### `std::map< std::string, std::string > vars`
📍 [tui.hpp:53](../../../../src/tui/tui.hpp#L53)
$var-style substitution table.
### `int screen_idx`
📍 [tui.hpp:56](../../../../src/tui/tui.hpp#L56)
### `std::vector< std::string > search_modules`
📍 [tui.hpp:59](../../../../src/tui/tui.hpp#L59)
### `std::vector< std::string > search_types`
📍 [tui.hpp:60](../../../../src/tui/tui.hpp#L60)
### `int search_module_idx`
📍 [tui.hpp:61](../../../../src/tui/tui.hpp#L61)
### `int search_type_idx`
📍 [tui.hpp:62](../../../../src/tui/tui.hpp#L62)
### `int search_focus_idx`
📍 [tui.hpp:63](../../../../src/tui/tui.hpp#L63)
### `std::string search_query`
📍 [tui.hpp:64](../../../../src/tui/tui.hpp#L64)
### `std::vector< std::string > connect_modules`
📍 [tui.hpp:67](../../../../src/tui/tui.hpp#L67)
### `int connect_m1_idx`
📍 [tui.hpp:68](../../../../src/tui/tui.hpp#L68)
### `int connect_m2_idx`
📍 [tui.hpp:69](../../../../src/tui/tui.hpp#L69)
### `std::string connect_p1_filter`
📍 [tui.hpp:70](../../../../src/tui/tui.hpp#L70)
### `std::string connect_p2_filter`
📍 [tui.hpp:71](../../../../src/tui/tui.hpp#L71)
### `std::vector< std::string > connect_p1_list`
📍 [tui.hpp:72](../../../../src/tui/tui.hpp#L72)
### `std::vector< std::string > connect_p2_list`
📍 [tui.hpp:73](../../../../src/tui/tui.hpp#L73)
### `int connect_p1_idx`
📍 [tui.hpp:74](../../../../src/tui/tui.hpp#L74)
### `int connect_p2_idx`
📍 [tui.hpp:75](../../../../src/tui/tui.hpp#L75)
### `int connect_focus_idx`
📍 [tui.hpp:76](../../../../src/tui/tui.hpp#L76)
### `std::vector< std::string > explore_modules`
📍 [tui.hpp:79](../../../../src/tui/tui.hpp#L79)
### `int explore_module_idx`
📍 [tui.hpp:80](../../../../src/tui/tui.hpp#L80)
### `std::vector< std::string > explore_types`
📍 [tui.hpp:81](../../../../src/tui/tui.hpp#L81)
### `int explore_type_idx`
📍 [tui.hpp:82](../../../../src/tui/tui.hpp#L82)
### `std::vector< std::string > explore_children`
📍 [tui.hpp:83](../../../../src/tui/tui.hpp#L83)
### `int explore_child_idx`
📍 [tui.hpp:84](../../../../src/tui/tui.hpp#L84)
### `std::string explore_child_filter`
📍 [tui.hpp:85](../../../../src/tui/tui.hpp#L85)
### `std::string explore_detail_filter`
📍 [tui.hpp:86](../../../../src/tui/tui.hpp#L86)
### `std::vector< std::string > explore_detail`
📍 [tui.hpp:87](../../../../src/tui/tui.hpp#L87)
### `int explore_detail_idx`
📍 [tui.hpp:88](../../../../src/tui/tui.hpp#L88)
### `std::string explore_header`
📍 [tui.hpp:89](../../../../src/tui/tui.hpp#L89)
### `int explore_focus_idx`
📍 [tui.hpp:90](../../../../src/tui/tui.hpp#L90)
### `std::atomic< bool > loading`
📍 [tui.hpp:93](../../../../src/tui/tui.hpp#L93)
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)
main thread acks each tick by clearing this; ticker waits.
### `std::string loading_filename`
📍 [tui.hpp:95](../../../../src/tui/tui.hpp#L95)
### `std::vector< std::string > loading_lines`
📍 [tui.hpp:96](../../../../src/tui/tui.hpp#L96)
### `size_t loading_idx`
📍 [tui.hpp:97](../../../../src/tui/tui.hpp#L97)
### `int loading_executed`
📍 [tui.hpp:98](../../../../src/tui/tui.hpp#L98)
### `int loading_lineno`
📍 [tui.hpp:99](../../../../src/tui/tui.hpp#L99)
### `bool loading_prev_in_source`
📍 [tui.hpp:100](../../../../src/tui/tui.hpp#L100)
### `ftxui::ScreenInteractive * screen_ptr`
📍 [tui.hpp:101](../../../../src/tui/tui.hpp#L101)
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)
### `int net_module_idx`
📍 [tui.hpp:105](../../../../src/tui/tui.hpp#L105)
### `std::string net_sig_filter`
📍 [tui.hpp:106](../../../../src/tui/tui.hpp#L106)
### `std::vector< std::string > net_sigs`
📍 [tui.hpp:107](../../../../src/tui/tui.hpp#L107)
rebuilt every frame from filter
### `int net_sig_idx`
📍 [tui.hpp:108](../../../../src/tui/tui.hpp#L108)
### `int net_focus_idx`
📍 [tui.hpp:109](../../../../src/tui/tui.hpp#L109)
### `std::vector< std::string > settype_modules`
📍 [tui.hpp:112](../../../../src/tui/tui.hpp#L112)
### `int settype_m_idx`
📍 [tui.hpp:113](../../../../src/tui/tui.hpp#L113)
### `std::string settype_p_filter`
📍 [tui.hpp:114](../../../../src/tui/tui.hpp#L114)
### `std::vector< std::string > settype_p_list`
📍 [tui.hpp:115](../../../../src/tui/tui.hpp#L115)
### `int settype_p_idx`
📍 [tui.hpp:116](../../../../src/tui/tui.hpp#L116)
### `std::string settype_type`
📍 [tui.hpp:117](../../../../src/tui/tui.hpp#L117)
### `std::string settype_status`
📍 [tui.hpp:118](../../../../src/tui/tui.hpp#L118)
### `int settype_focus_idx`
📍 [tui.hpp:119](../../../../src/tui/tui.hpp#L119)
## Public Functions
### `Tui()`
📍 [tui.hpp:122](../../../../src/tui/tui.hpp#L122)
### `~Tui()`
📍 [tui.hpp:123](../../../../src/tui/tui.hpp#L123)
### `void Run()`
📍 [tui.hpp:124](../../../../src/tui/tui.hpp#L124)
## Private Functions
### `void RegisterCommands()`
📍 [tui.hpp:128](../../../../src/tui/tui.hpp#L128)
### `void Print(const std::string &line)`
📍 [tui.hpp:131](../../../../src/tui/tui.hpp#L131)
### `void Submit()`
📍 [tui.hpp:132](../../../../src/tui/tui.hpp#L132)
### `void Dispatch(const std::string &raw)`
📍 [tui.hpp:133](../../../../src/tui/tui.hpp#L133)
### `void Finalize(const std::string &name, const CommandSpec &spec, const std::vector< std::string > &args)`
📍 [tui.hpp:134](../../../../src/tui/tui.hpp#L134)
### `void HistoryUp()`
📍 [tui.hpp:137](../../../../src/tui/tui.hpp#L137)
### `void HistoryDown()`
📍 [tui.hpp:138](../../../../src/tui/tui.hpp#L138)
### `void CancelPending()`
📍 [tui.hpp:139](../../../../src/tui/tui.hpp#L139)
### `void LoadHistory()`
📍 [tui.hpp:140](../../../../src/tui/tui.hpp#L140)
### `void AppendHistory(const std::string &cmd)`
📍 [tui.hpp:141](../../../../src/tui/tui.hpp#L141)
### `void Source(const std::string &filename)`
📍 [tui.hpp:142](../../../../src/tui/tui.hpp#L142)
### `void ProcessNextSourceLine()`
📍 [tui.hpp:143](../../../../src/tui/tui.hpp#L143)
### `std::string ExpandVars(const std::string &s) const`
📍 [tui.hpp:144](../../../../src/tui/tui.hpp#L144)
### `void CompleteCommand(size_t start=0)`
📍 [tui.hpp:147](../../../../src/tui/tui.hpp#L147)
### `void CompletePath(size_t start=0)`
📍 [tui.hpp:148](../../../../src/tui/tui.hpp#L148)
### `void CompleteInline()`
📍 [tui.hpp:149](../../../../src/tui/tui.hpp#L149)
### `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)
### `ftxui::Component BuildMainScreen(ftxui::ScreenInteractive &screen)`
📍 [tui.hpp:159](../../../../src/tui/tui.hpp#L159)
### `ftxui::Component BuildSearchScreen()`
📍 [tui.hpp:160](../../../../src/tui/tui.hpp#L160)
### `ftxui::Component BuildConnectScreen()`
📍 [tui.hpp:161](../../../../src/tui/tui.hpp#L161)
### `ftxui::Component BuildSettypeScreen()`
📍 [tui.hpp:162](../../../../src/tui/tui.hpp#L162)
### `ftxui::Component BuildExploreScreen()`
📍 [tui.hpp:163](../../../../src/tui/tui.hpp#L163)
### `ftxui::Component BuildNetScreen()`
📍 [tui.hpp:164](../../../../src/tui/tui.hpp#L164)
---
← [Back to classes](index.md) · [Top](../index.md)

37
doc/api/classes/Tui_1_1CommandSpec.md Normal file
View File

@@ -0,0 +1,37 @@
# Tui::CommandSpec
`struct Tui::CommandSpec`
Defined in [tui.hpp:26](../../../../src/tui/tui.hpp#L26)
## Public Attributes
### `std::vector< Param > params`
📍 [tui.hpp:31](../../../../src/tui/tui.hpp#L31)
### `std::function< void(const std::vector< std::string > &)> action`
📍 [tui.hpp:32](../../../../src/tui/tui.hpp#L32)
### `bool prompt_for_missing`
📍 [tui.hpp:33](../../../../src/tui/tui.hpp#L33)
### `std::string description`
📍 [tui.hpp:34](../../../../src/tui/tui.hpp#L34)
### `bool scriptable`
📍 [tui.hpp:35](../../../../src/tui/tui.hpp#L35)
### `bool interactive`
📍 [tui.hpp:36](../../../../src/tui/tui.hpp#L36)
opens a full-screen mode when called bare
---
← [Back to classes](index.md) · [Top](../index.md)

19
doc/api/classes/Tui_1_1CommandSpec_1_1Param.md Normal file
View File

@@ -0,0 +1,19 @@
# Tui::CommandSpec::Param
`struct Tui::CommandSpec::Param`
Defined in [tui.hpp:27](../../../../src/tui/tui.hpp#L27)
## Public Attributes
### `std::string name`
📍 [tui.hpp:28](../../../../src/tui/tui.hpp#L28)
### `Completion completion`
📍 [tui.hpp:29](../../../../src/tui/tui.hpp#L29)
---
← [Back to classes](index.md) · [Top](../index.md)

23
doc/api/classes/Tui_1_1Prompt.md Normal file
View File

@@ -0,0 +1,23 @@
# Tui::Prompt
`struct Tui::Prompt`
Defined in [tui.hpp:20](../../../../src/tui/tui.hpp#L20)
## Public Attributes
### `std::string question`
📍 [tui.hpp:21](../../../../src/tui/tui.hpp#L21)
### `std::function< void(const std::string &)> on_answer`
📍 [tui.hpp:22](../../../../src/tui/tui.hpp#L22)
### `Completion completion`
📍 [tui.hpp:23](../../../../src/tui/tui.hpp#L23)
---
← [Back to classes](index.md) · [Top](../index.md)

43
doc/api/classes/VpxTransform.md Normal file
View File

@@ -0,0 +1,43 @@
# VpxTransform
`class VpxTransform` — inherits [Transform](../classes/Transform.md)
Defined in [transform_vpx.hpp:23](../../../../src/system/transform_vpx.hpp#L23)
## Public Types
### `using VpxTransform::ColTable = std::map<char, char>`
📍 [transform_vpx.hpp:26](../../../../src/system/transform_vpx.hpp#L26)
## Private Attributes
### `std::string bkp_kind_`
📍 [transform_vpx.hpp:36](../../../../src/system/transform_vpx.hpp#L36)
### `std::string payload_kind_`
📍 [transform_vpx.hpp:37](../../../../src/system/transform_vpx.hpp#L37)
### `std::vector< ColTable > bkp_to_payload_`
📍 [transform_vpx.hpp:38](../../../../src/system/transform_vpx.hpp#L38)
### `std::vector< ColTable > payload_to_bkp_`
📍 [transform_vpx.hpp:39](../../../../src/system/transform_vpx.hpp#L39)
## Public Functions
### `VpxTransform(std::string name, std::string bkp_kind, std::string payload_kind, std::vector< ColTable > bkp_to_payload, std::vector< ColTable > payload_to_bkp)`
📍 [transform_vpx.hpp:28](../../../../src/system/transform_vpx.hpp#L28)
### `std::vector< std::pair< Pin *, Pin * > > apply(Part *a, Part *b) const override`
📍 [transform_vpx.hpp:33](../../../../src/system/transform_vpx.hpp#L33)
---
← [Back to classes](index.md) · [Top](../index.md)

30
doc/api/classes/index.md Normal file
View File

@@ -0,0 +1,30 @@
# Classes & Structs
| Name | Brief |
|---|---|
| [`Connection`](Connection.md) | — |
| [`Connections`](Connections.md) | — |
| [`IdentityTransform`](IdentityTransform.md) | — |
| [`ImportAltium`](ImportAltium.md) | — |
| [`ImportBase`](ImportBase.md) | Base class for importing data from a file. |
| [`ImportMentor`](ImportMentor.md) | — |
| [`ImportOds`](ImportOds.md) | — |
| [`Module`](Module.md) | Forward declaration of the [Signals](../classes/Signals.md) class. class. |
| [`Modules`](Modules.md) | — |
| [`Net`](Net.md) | — |
| [`Part`](Part.md) | Forward declaration of the [Module](../classes/Module.md) class. class. |
| [`Parts`](Parts.md) | — |
| [`Signal`](Signal.md) | — |
| [`Signals`](Signals.md) | — |
| [`System`](System.md) | — |
| [`SystemElement`](SystemElement.md) | Represents a basic system element with a name. |
| [`SystemElementContainer`](SystemElementContainer.md) | A container for managing system elements of type T. |
| [`Transform`](Transform.md) | — |
| [`TransformRegistry`](TransformRegistry.md) | — |
| [`Tui`](Tui.md) | — |
| [`Tui::CommandSpec`](Tui_1_1CommandSpec.md) | — |
| [`Tui::CommandSpec::Param`](Tui_1_1CommandSpec_1_1Param.md) | — |
| [`Tui::Prompt`](Tui_1_1Prompt.md) | — |
| [`VpxTransform`](VpxTransform.md) | — |
← [Top](../index.md)

7
doc/api/files/DESIGN_8md.md Normal file
View File

@@ -0,0 +1,7 @@
# DESIGN.md
Source: [DESIGN.md](../../../../DESIGN.md)
---
← [Back to files](index.md) · [Top](../index.md)

7
doc/api/files/README_8md.md Normal file
View File

@@ -0,0 +1,7 @@
# README.md
Source: [README.md](../../../../README.md)
---
← [Back to files](index.md) · [Top](../index.md)

7
doc/api/files/commands_8cpp.md Normal file
View File

@@ -0,0 +1,7 @@
# commands.cpp
Source: [commands.cpp](../../../../src/tui/commands.cpp)
---
← [Back to files](index.md) · [Top](../index.md)

7
doc/api/files/completion_8cpp.md Normal file
View File

@@ -0,0 +1,7 @@
# completion.cpp
Source: [completion.cpp](../../../../src/tui/completion.cpp)
---
← [Back to files](index.md) · [Top](../index.md)

21
doc/api/files/component__kind_8cpp.md Normal file
View File

@@ -0,0 +1,21 @@
# component_kind.cpp
Source: [component_kind.cpp](../../../../src/system/component_kind.cpp)
## Free Functions
### `const char * component_kind_name(ComponentKind k)`
📍 [component_kind.cpp:6](../../../../src/system/component_kind.cpp#L6)
### `bool component_kind_from_name(const std::string &s, ComponentKind &out)`
📍 [component_kind.cpp:21](../../../../src/system/component_kind.cpp#L21)
### `ComponentKind infer_component_kind(const std::string &part_name)`
📍 [component_kind.cpp:37](../../../../src/system/component_kind.cpp#L37)
---
← [Back to files](index.md) · [Top](../index.md)

27
doc/api/files/component__kind_8hpp.md Normal file
View File

@@ -0,0 +1,27 @@
# component_kind.hpp
Source: [component_kind.hpp](../../../../src/system/component_kind.hpp)
## Enums
### `enum ComponentKind`
📍 [component_kind.hpp:10](../../../../src/system/component_kind.hpp#L10)
## Free Functions
### `const char * component_kind_name(ComponentKind k)`
📍 [component_kind.hpp:22](../../../../src/system/component_kind.hpp#L22)
### `bool component_kind_from_name(const std::string &s, ComponentKind &out)`
📍 [component_kind.hpp:23](../../../../src/system/component_kind.hpp#L23)
### `ComponentKind infer_component_kind(const std::string &part_name)`
📍 [component_kind.hpp:24](../../../../src/system/component_kind.hpp#L24)
---
← [Back to files](index.md) · [Top](../index.md)

7
doc/api/files/connect_8cpp.md Normal file
View File

@@ -0,0 +1,7 @@
# connect.cpp
Source: [connect.cpp](../../../../src/system/connect.cpp)
---
← [Back to files](index.md) · [Top](../index.md)

12
doc/api/files/connect_8hpp.md Normal file
View File

@@ -0,0 +1,12 @@
# connect.hpp
Source: [connect.hpp](../../../../src/system/connect.hpp)
## Defines
- [Connection](../classes/Connection.md)
- [Connections](../classes/Connections.md)
---
← [Back to files](index.md) · [Top](../index.md)

7
doc/api/files/import__altium_8cpp.md Normal file
View File

@@ -0,0 +1,7 @@
# import_altium.cpp
Source: [import_altium.cpp](../../../../src/imports/import_altium.cpp)
---
← [Back to files](index.md) · [Top](../index.md)

11
doc/api/files/import__altium_8hpp.md Normal file
View File

@@ -0,0 +1,11 @@
# import_altium.hpp
Source: [import_altium.hpp](../../../../src/imports/import_altium.hpp)
## Defines
- [ImportAltium](../classes/ImportAltium.md)
---
← [Back to files](index.md) · [Top](../index.md)

11
doc/api/files/import__base_8hpp.md Normal file
View File

@@ -0,0 +1,11 @@
# import_base.hpp
Source: [import_base.hpp](../../../../src/imports/import_base.hpp)
## Defines
- [ImportBase](../classes/ImportBase.md)
---
← [Back to files](index.md) · [Top](../index.md)

18
doc/api/files/import__mentor_8cpp.md Normal file
View File

@@ -0,0 +1,18 @@
# import_mentor.cpp
Source: [import_mentor.cpp](../../../../src/imports/import_mentor.cpp)
## Enums
### `enum State`
📍 [import_mentor.cpp:17](../../../../src/imports/import_mentor.cpp#L17)
Enum representing the parsing state.
- NO_PART: No part is currently being processed.
- IS_PART: A part is currently being processed.
---
← [Back to files](index.md) · [Top](../index.md)

11
doc/api/files/import__mentor_8hpp.md Normal file
View File

@@ -0,0 +1,11 @@
# import_mentor.hpp
Source: [import_mentor.hpp](../../../../src/imports/import_mentor.hpp)
## Defines
- [ImportMentor](../classes/ImportMentor.md)
---
← [Back to files](index.md) · [Top](../index.md)

21
doc/api/files/import__ods_8cpp.md Normal file
View File

@@ -0,0 +1,21 @@
# import_ods.cpp
Source: [import_ods.cpp](../../../../src/imports/import_ods.cpp)
## Free Functions
### `std::string read_content_xml(const std::string &filename)`
📍 [import_ods.cpp:17](../../../../src/imports/import_ods.cpp#L17)
### `std::string cell_text(pugi::xml_node cell)`
📍 [import_ods.cpp:45](../../../../src/imports/import_ods.cpp#L45)
### `std::vector< std::string > expand_row(pugi::xml_node row)`
📍 [import_ods.cpp:57](../../../../src/imports/import_ods.cpp#L57)
---
← [Back to files](index.md) · [Top](../index.md)

11
doc/api/files/import__ods_8hpp.md Normal file
View File

@@ -0,0 +1,11 @@
# import_ods.hpp
Source: [import_ods.hpp](../../../../src/imports/import_ods.hpp)
## Defines
- [ImportOds](../classes/ImportOds.md)
---
← [Back to files](index.md) · [Top](../index.md)

57
doc/api/files/index.md Normal file
View File

@@ -0,0 +1,57 @@
# Source Files
| Path | Brief |
|---|---|
| [`commands.cpp`](commands_8cpp.md) | — |
| [`completion.cpp`](completion_8cpp.md) | — |
| [`component_kind.cpp`](component__kind_8cpp.md) | — |
| [`component_kind.hpp`](component__kind_8hpp.md) | — |
| [`connect.cpp`](connect_8cpp.md) | — |
| [`connect.hpp`](connect_8hpp.md) | — |
| [`DESIGN.md`](DESIGN_8md.md) | — |
| [`import_altium.cpp`](import__altium_8cpp.md) | — |
| [`import_altium.hpp`](import__altium_8hpp.md) | — |
| [`import_base.hpp`](import__base_8hpp.md) | — |
| [`import_mentor.cpp`](import__mentor_8cpp.md) | — |
| [`import_mentor.hpp`](import__mentor_8hpp.md) | — |
| [`import_ods.cpp`](import__ods_8cpp.md) | — |
| [`import_ods.hpp`](import__ods_8hpp.md) | — |
| [`main.cpp`](main_8cpp.md) | — |
| [`modules.cpp`](modules_8cpp.md) | — |
| [`modules.hpp`](modules_8hpp.md) | — |
| [`nets.cpp`](nets_8cpp.md) | — |
| [`nets.hpp`](nets_8hpp.md) | — |
| [`parts.cpp`](parts_8cpp.md) | — |
| [`parts.hpp`](parts_8hpp.md) | — |
| [`persist.cpp`](persist_8cpp.md) | — |
| [`persist.hpp`](persist_8hpp.md) | — |
| [`pin_name.cpp`](pin__name_8cpp.md) | — |
| [`pin_name.hpp`](pin__name_8hpp.md) | — |
| [`pin_role.cpp`](pin__role_8cpp.md) | — |
| [`pin_role.hpp`](pin__role_8hpp.md) | — |
| [`pins.cpp`](pins_8cpp.md) | — |
| [`pins.hpp`](pins_8hpp.md) | — |
| [`README.md`](README_8md.md) | — |
| [`screen_connect.cpp`](screen__connect_8cpp.md) | — |
| [`screen_explore.cpp`](screen__explore_8cpp.md) | — |
| [`screen_main.cpp`](screen__main_8cpp.md) | — |
| [`screen_net.cpp`](screen__net_8cpp.md) | — |
| [`screen_search.cpp`](screen__search_8cpp.md) | — |
| [`screen_settype.cpp`](screen__settype_8cpp.md) | — |
| [`shell.cpp`](shell_8cpp.md) | — |
| [`signal_type.hpp`](signal__type_8hpp.md) | — |
| [`signals.cpp`](signals_8cpp.md) | — |
| [`signals.hpp`](signals_8hpp.md) | — |
| [`syselmts.hpp`](syselmts_8hpp.md) | — |
| [`system.cpp`](system_8cpp.md) | — |
| [`system.hpp`](system_8hpp.md) | — |
| [`transform.cpp`](transform_8cpp.md) | — |
| [`transform.hpp`](transform_8hpp.md) | — |
| [`transform_vpx.cpp`](transform__vpx_8cpp.md) | — |
| [`transform_vpx.hpp`](transform__vpx_8hpp.md) | — |
| [`tui.cpp`](tui_8cpp.md) | — |
| [`tui.hpp`](tui_8hpp.md) | — |
| [`tui_helpers.cpp`](tui__helpers_8cpp.md) | — |
| [`tui_helpers.hpp`](tui__helpers_8hpp.md) | — |
← [Top](../index.md)

13
doc/api/files/main_8cpp.md Normal file
View File

@@ -0,0 +1,13 @@
# main.cpp
Source: [main.cpp](../../../../src/main.cpp)
## Free Functions
### `int main()`
📍 [main.cpp:3](../../../../src/main.cpp#L3)
---
← [Back to files](index.md) · [Top](../index.md)

7
doc/api/files/modules_8cpp.md Normal file
View File

@@ -0,0 +1,7 @@
# modules.cpp
Source: [modules.cpp](../../../../src/system/modules.cpp)
---
← [Back to files](index.md) · [Top](../index.md)

12
doc/api/files/modules_8hpp.md Normal file
View File

@@ -0,0 +1,12 @@
# modules.hpp
Source: [modules.hpp](../../../../src/system/modules.hpp)
## Defines
- [Module](../classes/Module.md)
- [Modules](../classes/Modules.md)
---
← [Back to files](index.md) · [Top](../index.md)

25
doc/api/files/nets_8cpp.md Normal file
View File

@@ -0,0 +1,25 @@
# nets.cpp
Source: [nets.cpp](../../../../src/system/nets.cpp)
## Free Functions
### `Net find_net(System *sys, Module *m, Signal *s)`
📍 [nets.cpp:69](../../../../src/system/nets.cpp#L69)
### `Net find_net(System *sys, Pin *pin)`
📍 [nets.cpp:78](../../../../src/system/nets.cpp#L78)
### `std::vector< Net > compute_all_nets(System *sys)`
📍 [nets.cpp:83](../../../../src/system/nets.cpp#L83)
### `bool net_type_consistent(const Net &net, SignalType &dominant)`
📍 [nets.cpp:102](../../../../src/system/nets.cpp#L102)
---
← [Back to files](index.md) · [Top](../index.md)

29
doc/api/files/nets_8hpp.md Normal file
View File

@@ -0,0 +1,29 @@
# nets.hpp
Source: [nets.hpp](../../../../src/system/nets.hpp)
## Defines
- [Net](../classes/Net.md)
## Free Functions
### `Net find_net(System *sys, Module *m, Signal *s)`
📍 [nets.hpp:21](../../../../src/system/nets.hpp#L21)
### `Net find_net(System *sys, Pin *pin)`
📍 [nets.hpp:24](../../../../src/system/nets.hpp#L24)
### `std::vector< Net > compute_all_nets(System *sys)`
📍 [nets.hpp:28](../../../../src/system/nets.hpp#L28)
### `bool net_type_consistent(const Net &net, SignalType &dominant)`
📍 [nets.hpp:32](../../../../src/system/nets.hpp#L32)
---
← [Back to files](index.md) · [Top](../index.md)

7
doc/api/files/parts_8cpp.md Normal file
View File

@@ -0,0 +1,7 @@
# parts.cpp
Source: [parts.cpp](../../../../src/system/parts.cpp)
---
← [Back to files](index.md) · [Top](../index.md)

12
doc/api/files/parts_8hpp.md Normal file
View File

@@ -0,0 +1,12 @@
# parts.hpp
Source: [parts.hpp](../../../../src/system/parts.hpp)
## Defines
- [Part](../classes/Part.md)
- [Parts](../classes/Parts.md)
---
← [Back to files](index.md) · [Top](../index.md)

17
doc/api/files/persist_8cpp.md Normal file
View File

@@ -0,0 +1,17 @@
# persist.cpp
Source: [persist.cpp](../../../../src/system/persist.cpp)
## Free Functions
### `bool save_system(const System *sys, const std::string &filename, std::string &error)`
📍 [persist.cpp:32](../../../../src/system/persist.cpp#L32)
### `System * restore_system(const std::string &filename, std::string &error)`
📍 [persist.cpp:84](../../../../src/system/persist.cpp#L84)
---
← [Back to files](index.md) · [Top](../index.md)

17
doc/api/files/persist_8hpp.md Normal file
View File

@@ -0,0 +1,17 @@
# persist.hpp
Source: [persist.hpp](../../../../src/system/persist.hpp)
## Free Functions
### `bool save_system(const System *sys, const std::string &filename, std::string &error)`
📍 [persist.hpp:10](../../../../src/system/persist.hpp#L10)
### `System * restore_system(const std::string &filename, std::string &error)`
📍 [persist.hpp:14](../../../../src/system/persist.hpp#L14)
---
← [Back to files](index.md) · [Top](../index.md)

13
doc/api/files/pin__name_8cpp.md Normal file
View File

@@ -0,0 +1,13 @@
# pin_name.cpp
Source: [pin_name.cpp](../../../../src/system/pin_name.cpp)
## Free Functions
### `std::string canonical_pin_name(const std::string &name)`
📍 [pin_name.cpp:7](../../../../src/system/pin_name.cpp#L7)
---
← [Back to files](index.md) · [Top](../index.md)

13
doc/api/files/pin__name_8hpp.md Normal file
View File

@@ -0,0 +1,13 @@
# pin_name.hpp
Source: [pin_name.hpp](../../../../src/system/pin_name.hpp)
## Free Functions
### `std::string canonical_pin_name(const std::string &name)`
📍 [pin_name.hpp:23](../../../../src/system/pin_name.hpp#L23)
---
← [Back to files](index.md) · [Top](../index.md)

21
doc/api/files/pin__role_8cpp.md Normal file
View File

@@ -0,0 +1,21 @@
# pin_role.cpp
Source: [pin_role.cpp](../../../../src/system/pin_role.cpp)
## Free Functions
### `SignalType pin_role(const std::string &kind, const std::string &pin_name)`
📍 [pin_role.cpp:43](../../../../src/system/pin_role.cpp#L43)
### `std::vector< std::string > pin_layout(const std::string &kind)`
📍 [pin_role.cpp:63](../../../../src/system/pin_role.cpp#L63)
### `int FillPartFromLayout(Part *p, const std::string &kind)`
📍 [pin_role.cpp:73](../../../../src/system/pin_role.cpp#L73)
---
← [Back to files](index.md) · [Top](../index.md)

21
doc/api/files/pin__role_8hpp.md Normal file
View File

@@ -0,0 +1,21 @@
# pin_role.hpp
Source: [pin_role.hpp](../../../../src/system/pin_role.hpp)
## Free Functions
### `SignalType pin_role(const std::string &connector_type, const std::string &pin_name)`
📍 [pin_role.hpp:18](../../../../src/system/pin_role.hpp#L18)
### `std::vector< std::string > pin_layout(const std::string &connector_type)`
📍 [pin_role.hpp:29](../../../../src/system/pin_role.hpp#L29)
### `int FillPartFromLayout(Part *p, const std::string &connector_type)`
📍 [pin_role.hpp:34](../../../../src/system/pin_role.hpp#L34)
---
← [Back to files](index.md) · [Top](../index.md)

7
doc/api/files/pins_8cpp.md Normal file
View File

@@ -0,0 +1,7 @@
# pins.cpp
Source: [pins.cpp](../../../../src/system/pins.cpp)
---
← [Back to files](index.md) · [Top](../index.md)

7
doc/api/files/pins_8hpp.md Normal file
View File

@@ -0,0 +1,7 @@
# pins.hpp
Source: [pins.hpp](../../../../src/system/pins.hpp)
---
← [Back to files](index.md) · [Top](../index.md)

7
doc/api/files/screen__connect_8cpp.md Normal file
View File

@@ -0,0 +1,7 @@
# screen_connect.cpp
Source: [screen_connect.cpp](../../../../src/tui/screen_connect.cpp)
---
← [Back to files](index.md) · [Top](../index.md)

7
doc/api/files/screen__explore_8cpp.md Normal file
View File

@@ -0,0 +1,7 @@
# screen_explore.cpp
Source: [screen_explore.cpp](../../../../src/tui/screen_explore.cpp)
---
← [Back to files](index.md) · [Top](../index.md)

7
doc/api/files/screen__main_8cpp.md Normal file
View File

@@ -0,0 +1,7 @@
# screen_main.cpp
Source: [screen_main.cpp](../../../../src/tui/screen_main.cpp)
---
← [Back to files](index.md) · [Top](../index.md)

7
doc/api/files/screen__net_8cpp.md Normal file
View File

@@ -0,0 +1,7 @@
# screen_net.cpp
Source: [screen_net.cpp](../../../../src/tui/screen_net.cpp)
---
← [Back to files](index.md) · [Top](../index.md)

7
doc/api/files/screen__search_8cpp.md Normal file
View File

@@ -0,0 +1,7 @@
# screen_search.cpp
Source: [screen_search.cpp](../../../../src/tui/screen_search.cpp)
---
← [Back to files](index.md) · [Top](../index.md)

7
doc/api/files/screen__settype_8cpp.md Normal file
View File

@@ -0,0 +1,7 @@
# screen_settype.cpp
Source: [screen_settype.cpp](../../../../src/tui/screen_settype.cpp)
---
← [Back to files](index.md) · [Top](../index.md)

7
doc/api/files/shell_8cpp.md Normal file
View File

@@ -0,0 +1,7 @@
# shell.cpp
Source: [shell.cpp](../../../../src/tui/shell.cpp)
---
← [Back to files](index.md) · [Top](../index.md)

27
doc/api/files/signal__type_8hpp.md Normal file
View File

@@ -0,0 +1,27 @@
# signal_type.hpp
Source: [signal_type.hpp](../../../../src/system/signal_type.hpp)
## Enums
### `enum SignalType`
📍 [signal_type.hpp:6](../../../../src/system/signal_type.hpp#L6)
## Free Functions
### `const char * signal_type_name(SignalType t)`
📍 [signal_type.hpp:8](../../../../src/system/signal_type.hpp#L8)
### `bool signal_type_from_name(const std::string &s, SignalType &out)`
📍 [signal_type.hpp:9](../../../../src/system/signal_type.hpp#L9)
### `SignalType infer_signal_type(const std::string &signal_name)`
📍 [signal_type.hpp:10](../../../../src/system/signal_type.hpp#L10)
---
← [Back to files](index.md) · [Top](../index.md)

21
doc/api/files/signals_8cpp.md Normal file
View File

@@ -0,0 +1,21 @@
# signals.cpp
Source: [signals.cpp](../../../../src/system/signals.cpp)
## Free Functions
### `const char * signal_type_name(SignalType t)`
📍 [signals.cpp:9](../../../../src/system/signals.cpp#L9)
### `bool signal_type_from_name(const std::string &s, SignalType &out)`
📍 [signals.cpp:18](../../../../src/system/signals.cpp#L18)
### `SignalType infer_signal_type(const std::string &name)`
📍 [signals.cpp:33](../../../../src/system/signals.cpp#L33)
---
← [Back to files](index.md) · [Top](../index.md)

12
doc/api/files/signals_8hpp.md Normal file
View File

@@ -0,0 +1,12 @@
# signals.hpp
Source: [signals.hpp](../../../../src/system/signals.hpp)
## Defines
- [Signal](../classes/Signal.md)
- [Signals](../classes/Signals.md)
---
← [Back to files](index.md) · [Top](../index.md)

12
doc/api/files/syselmts_8hpp.md Normal file
View File

@@ -0,0 +1,12 @@
# syselmts.hpp
Source: [syselmts.hpp](../../../../src/system/syselmts.hpp)
## Defines
- [SystemElement](../classes/SystemElement.md)
- [SystemElementContainer](../classes/SystemElementContainer.md)
---
← [Back to files](index.md) · [Top](../index.md)

7
doc/api/files/system_8cpp.md Normal file
View File

@@ -0,0 +1,7 @@
# system.cpp
Source: [system.cpp](../../../../src/system/system.cpp)
---
← [Back to files](index.md) · [Top](../index.md)

19
doc/api/files/system_8hpp.md Normal file
View File

@@ -0,0 +1,19 @@
# system.hpp
Source: [system.hpp](../../../../src/system/system.hpp)
## Defines
- [System](../classes/System.md)
## Enums
### `enum ImportType`
📍 [system.hpp:11](../../../../src/system/system.hpp#L11)
Forward declaration of the [Connections](../classes/Connections.md) class. class.
---
← [Back to files](index.md) · [Top](../index.md)

17
doc/api/files/transform_8cpp.md Normal file
View File

@@ -0,0 +1,17 @@
# transform.cpp
Source: [transform.cpp](../../../../src/system/transform.cpp)
## Free Functions
### `std::string CheckIdentityCompatible(const Part *a, const Part *b, std::string *info)`
📍 [transform.cpp:17](../../../../src/system/transform.cpp#L17)
### `int FillIdentityNCs(Part *a, Part *b)`
📍 [transform.cpp:59](../../../../src/system/transform.cpp#L59)
---
← [Back to files](index.md) · [Top](../index.md)

23
doc/api/files/transform_8hpp.md Normal file
View File

@@ -0,0 +1,23 @@
# transform.hpp
Source: [transform.hpp](../../../../src/system/transform.hpp)
## Defines
- [Transform](../classes/Transform.md)
- [IdentityTransform](../classes/IdentityTransform.md)
- [TransformRegistry](../classes/TransformRegistry.md)
## Free Functions
### `std::string CheckIdentityCompatible(const Part *a, const Part *b, std::string *info=nullptr)`
📍 [transform.hpp:22](../../../../src/system/transform.hpp#L22)
### `int FillIdentityNCs(Part *a, Part *b)`
📍 [transform.hpp:29](../../../../src/system/transform.hpp#L29)
---
← [Back to files](index.md) · [Top](../index.md)

17
doc/api/files/transform__vpx_8cpp.md Normal file
View File

@@ -0,0 +1,17 @@
# transform_vpx.cpp
Source: [transform_vpx.cpp](../../../../src/system/transform_vpx.cpp)
## Free Functions
### `std::string ValidatePartForKind(const Part *p, const std::string &kind)`
📍 [transform_vpx.cpp:159](../../../../src/system/transform_vpx.cpp#L159)
### `void RegisterVpxTransforms(TransformRegistry &reg)`
📍 [transform_vpx.cpp:190](../../../../src/system/transform_vpx.cpp#L190)
---
← [Back to files](index.md) · [Top](../index.md)

21
doc/api/files/transform__vpx_8hpp.md Normal file
View File

@@ -0,0 +1,21 @@
# transform_vpx.hpp
Source: [transform_vpx.hpp](../../../../src/system/transform_vpx.hpp)
## Defines
- [VpxTransform](../classes/VpxTransform.md)
## Free Functions
### `void RegisterVpxTransforms(TransformRegistry &reg)`
📍 [transform_vpx.hpp:43](../../../../src/system/transform_vpx.hpp#L43)
### `std::string ValidatePartForKind(const Part *p, const std::string &kind)`
📍 [transform_vpx.hpp:50](../../../../src/system/transform_vpx.hpp#L50)
---
← [Back to files](index.md) · [Top](../index.md)

7
doc/api/files/tui_8cpp.md Normal file
View File

@@ -0,0 +1,7 @@
# tui.cpp
Source: [tui.cpp](../../../../src/tui/tui.cpp)
---
← [Back to files](index.md) · [Top](../index.md)

14
doc/api/files/tui_8hpp.md Normal file
View File

@@ -0,0 +1,14 @@
# tui.hpp
Source: [tui.hpp](../../../../src/tui/tui.hpp)
## Defines
- [Tui](../classes/Tui.md)
- `Tui::Prompt`
- `Tui::CommandSpec`
- `Tui::CommandSpec::Param`
---
← [Back to files](index.md) · [Top](../index.md)

25
doc/api/files/tui__helpers_8cpp.md Normal file
View File

@@ -0,0 +1,25 @@
# tui_helpers.cpp
Source: [tui_helpers.cpp](../../../../src/tui/tui_helpers.cpp)
## Free Functions
### `std::string ToLower(std::string s)`
📍 [tui_helpers.cpp:6](../../../../src/tui/tui_helpers.cpp#L6)
### `bool NaturalLess(const std::string &a, const std::string &b)`
📍 [tui_helpers.cpp:12](../../../../src/tui/tui_helpers.cpp#L12)
### `std::string LongestCommonPrefix(const std::vector< std::string > &v)`
📍 [tui_helpers.cpp:45](../../../../src/tui/tui_helpers.cpp#L45)
### `std::vector< std::string > Tokenize(const std::string &s)`
📍 [tui_helpers.cpp:56](../../../../src/tui/tui_helpers.cpp#L56)
---
← [Back to files](index.md) · [Top](../index.md)

29
doc/api/files/tui__helpers_8hpp.md Normal file
View File

@@ -0,0 +1,29 @@
# tui_helpers.hpp
Source: [tui_helpers.hpp](../../../../src/tui/tui_helpers.hpp)
## Free Functions
### `ftxui::Element FocusLabel(ftxui::Element e, bool focused)`
📍 [tui_helpers.hpp:13](../../../../src/tui/tui_helpers.hpp#L13)
### `std::string ToLower(std::string s)`
📍 [tui_helpers.hpp:17](../../../../src/tui/tui_helpers.hpp#L17)
### `bool NaturalLess(const std::string &a, const std::string &b)`
📍 [tui_helpers.hpp:21](../../../../src/tui/tui_helpers.hpp#L21)
### `std::string LongestCommonPrefix(const std::vector< std::string > &v)`
📍 [tui_helpers.hpp:23](../../../../src/tui/tui_helpers.hpp#L23)
### `std::vector< std::string > Tokenize(const std::string &s)`
📍 [tui_helpers.hpp:26](../../../../src/tui/tui_helpers.hpp#L26)
---
← [Back to files](index.md) · [Top](../index.md)

20
doc/api/index.md Normal file
View File

@@ -0,0 +1,20 @@
# essim API reference
Auto-generated from Doxygen comments in `src/`. Regenerate with
`cmake --build build --target doc`. See [doc/README.md](../README.md)
for the toolchain.
- [Classes & Structs](classes/index.md) — 24 entries
- [Source Files](files/index.md) — 51 entries
## Curated reading order
Start with the domain model, then importers, then the TUI:
1. [`System`](classes/System.md) — owns Modules + Connections.
2. [`Module`](classes/Module.md) → [`Part`](classes/Part.md) → [`Pin`](classes/Pin.md) → [`Signal`](classes/Signal.md) — ownership chain.
3. [`Connection`](classes/Connection.md) — cross-module wiring with `pin_map`.
4. [`Transform`](classes/Transform.md) / [`IdentityTransform`](classes/IdentityTransform.md) — connector-pair → pin pairs.
5. [`ImportBase`](classes/ImportBase.md) → [`ImportMentor`](classes/ImportMentor.md), [`ImportAltium`](classes/ImportAltium.md), [`ImportOds`](classes/ImportOds.md) — netlist parsers.
6. [`Tui`](classes/Tui.md) — interactive shell + screen orchestration.

533
doc/gen_api_md.py Normal file
View File

@@ -0,0 +1,533 @@
#!/usr/bin/env python3
"""
Convert the Doxygen XML output to a Markdown tree readable directly by
gitea's web interface.
Usage:
python3 doc/gen_api_md.py <xml_dir> <out_dir>
Layout produced (rooted at <out_dir>):
index.md — landing page (classes + files TOC)
classes/
index.md — table of classes
<Name>.md — one per class/struct (members, briefs, source links)
files/
index.md — table of source files
<name>.md — one per file (compounds defined + free funcs)
Source links use relative paths so gitea turns them into clickable links
straight to the right line of the source file.
"""
from __future__ import annotations
import re
import sys
import xml.etree.ElementTree as ET
from pathlib import Path
# ----------------------------------------------------------------------
# Inline rendering helpers
# ----------------------------------------------------------------------
CLASS_REFID_RE = re.compile(r"^(class|struct)([A-Za-z_].*)$")
def ref_to_md(refid: str, label: str) -> str:
"""Turn a Doxygen refid into a Markdown link target if it points to a
known class/struct, otherwise just return the label.
Links are emitted relative to the `doc/api/` root (so they resolve
identically from `classes/` and `files/` pages thanks to the
intervening `..`)."""
if not refid:
return label
m = CLASS_REFID_RE.match(refid)
if m and "_1" not in refid:
return f"[{label}](../classes/{m.group(2)}.md)"
return f"`{label}`" if label else refid
def plain_text(elem: ET.Element | None) -> str:
"""Render an element as plain text — no Markdown, no links. Used inside
code spans where Markdown syntax wouldn't be rendered anyway."""
if elem is None:
return ""
parts: list[str] = []
if elem.text:
parts.append(elem.text)
for c in elem:
parts.append(plain_text(c))
if c.tail:
parts.append(c.tail)
return "".join(parts)
def inline_md(elem: ET.Element | None) -> str:
"""Render a Doxygen inline-text element as Markdown."""
if elem is None:
return ""
out: list[str] = []
if elem.text:
out.append(elem.text)
for c in elem:
tag = c.tag
if tag == "ref":
out.append(ref_to_md(c.attrib.get("refid", ""), (c.text or "").strip()))
elif tag == "computeroutput":
out.append("`" + inline_md(c).strip() + "`")
elif tag == "emphasis":
out.append("*" + inline_md(c) + "*")
elif tag == "bold":
out.append("**" + inline_md(c) + "**")
elif tag == "linebreak":
out.append(" \n")
elif tag == "ulink":
href = c.attrib.get("url", "")
out.append(f"[{(c.text or href).strip()}]({href})")
elif tag == "verbatim":
out.append("\n\n```\n" + (c.text or "") + "\n```\n\n")
else:
# Unknown / generic container: recurse, preserves nested text.
out.append(inline_md(c))
if c.tail:
out.append(c.tail)
return "".join(out)
def render_para(para: ET.Element) -> tuple[str, list[tuple[str, str]],
list[str], list[tuple[str, str]]]:
"""Render one <para> element. Returns (prose, params, returns, throws).
Parameter / return / throws annotations from the para are pulled out
so the caller can lay them out separately.
"""
params: list[tuple[str, str]] = []
returns: list[str] = []
throws: list[tuple[str, str]] = []
out: list[str] = []
if para.text:
out.append(para.text)
for c in para:
tag = c.tag
if tag == "parameterlist":
kind = c.attrib.get("kind", "")
for pi in c.findall("parameteritem"):
name_el = pi.find("parameternamelist/parametername")
name = (name_el.text or "").strip() if name_el is not None else ""
desc = inline_md(pi.find("parameterdescription")).strip()
if kind == "param":
params.append((name, desc))
elif kind == "exception":
throws.append((name, desc))
elif tag == "simplesect":
kind = c.attrib.get("kind", "")
if kind == "return":
returns.append(inline_md(c).strip())
elif kind in ("note", "warning"):
out.append(f"\n\n> **{kind.capitalize()}:** {inline_md(c).strip()}\n\n")
elif tag == "programlisting":
out.append("\n\n```cpp\n")
for codeline in c.findall("codeline"):
out.append("".join(codeline.itertext()) + "\n")
out.append("```\n\n")
elif tag == "itemizedlist":
out.append("\n\n")
for li in c.findall("listitem"):
out.append("- " + "\n ".join(
render_para(p)[0].strip() for p in li.findall("para")
) + "\n")
out.append("\n")
elif tag in ("ref", "computeroutput", "emphasis", "bold",
"linebreak", "ulink", "verbatim"):
# Reuse inline_md for one-element rendering.
wrap = ET.Element("_w")
wrap.append(c)
out.append(inline_md(wrap).rstrip())
else:
out.append(inline_md(c))
if c.tail:
out.append(c.tail)
return "".join(out).strip(), params, returns, throws
def render_description(elem: ET.Element | None) -> tuple[str, list[tuple[str, str]],
list[str], list[tuple[str, str]]]:
"""Render <briefdescription> or <detaileddescription> as Markdown +
extract @param / @return / @throws lists."""
if elem is None:
return "", [], [], []
paras: list[str] = []
params: list[tuple[str, str]] = []
returns: list[str] = []
throws: list[tuple[str, str]] = []
for p in elem.findall("para"):
prose, ps, rs, ts = render_para(p)
if prose:
paras.append(prose)
params.extend(ps)
returns.extend(rs)
throws.extend(ts)
return "\n\n".join(paras), params, returns, throws
# ----------------------------------------------------------------------
# Source link helpers
# ----------------------------------------------------------------------
def src_link(loc: ET.Element | None, depth_to_root: int = 2) -> str:
"""Build a relative Markdown link to the source location.
depth_to_root = number of `..` segments to escape from the .md page
back to the repo root. Class/file pages live at `doc/api/<sub>/<x>.md`,
so depth 2 (to `doc/api/`) + an extra 2 to get back to the repo root.
"""
if loc is None:
return ""
file_ = loc.attrib.get("file", "")
line = loc.attrib.get("line", "")
if not file_:
return ""
prefix = "../" * (depth_to_root + 2) # ../../../../ from doc/api/<sub>/<x>.md
target = f"{prefix}{file_}"
if line:
target += f"#L{line}"
label = Path(file_).name + (f":{line}" if line else "")
return f"[{label}]({target})"
# ----------------------------------------------------------------------
# Compound rendering
# ----------------------------------------------------------------------
def member_signature(m: ET.Element) -> str:
"""Reconstruct a member's C++ declaration as it should appear in the doc.
Uses plain text for the type (no Markdown links) since the signature
sits inside a code span where Markdown isn't rendered anyway. Whitespace
is normalised so that `Signals *` and `Signals*` look the same.
"""
kind = m.attrib.get("kind", "")
type_ = plain_text(m.find("type")).strip()
type_ = re.sub(r"\s+", " ", type_)
name = (m.findtext("name") or "").strip()
if kind == "function":
argstr = (m.findtext("argsstring") or "").strip()
return f"{type_} {name}{argstr}".strip() if type_ else f"{name}{argstr}"
if kind == "variable":
return f"{type_} {name}".strip()
if kind == "enum":
return f"enum {name}"
if kind == "typedef":
defn = (m.findtext("definition") or "").strip()
return defn or f"typedef {type_} {name}"
return name
def emit_class(xml_dir: Path, out_dir: Path, refid: str) -> None:
tree = ET.parse(xml_dir / f"{refid}.xml")
root = tree.find("compounddef")
if root is None:
return
kind = root.attrib.get("kind", "class")
name = (root.findtext("compoundname") or "").strip()
out_path = out_dir / "classes" / f"{refid[5 if kind == 'class' else 6:]}.md"
lines: list[str] = []
lines.append(f"# {name}")
lines.append("")
header_bits = [f"`{kind} {name}`"]
bases = []
for b in root.findall("basecompoundref"):
label = (b.text or "").strip()
bases.append(ref_to_md(b.attrib.get("refid", ""), label))
if bases:
header_bits.append("— inherits " + ", ".join(bases))
lines.append(" ".join(header_bits))
lines.append("")
loc = root.find("location")
if loc is not None and loc.attrib.get("file"):
lines.append(f"Defined in {src_link(loc)}")
lines.append("")
brief, _, _, _ = render_description(root.find("briefdescription"))
if brief:
lines.append(brief)
lines.append("")
detailed, _, _, _ = render_description(root.find("detaileddescription"))
if detailed:
lines.append(detailed)
lines.append("")
section_titles = {
"public-type": "Public Types",
"public-attrib": "Public Attributes",
"public-static-attrib": "Public Static Attributes",
"public-func": "Public Functions",
"public-static-func": "Public Static Functions",
"protected-attrib": "Protected Attributes",
"protected-func": "Protected Functions",
"private-attrib": "Private Attributes",
"private-func": "Private Functions",
"user-defined": "User-defined",
}
for sec in root.findall("sectiondef"):
sk = sec.attrib.get("kind", "")
title = section_titles.get(sk, sk.replace("-", " ").capitalize())
members = sec.findall("memberdef")
if not members:
continue
lines.append(f"## {title}")
lines.append("")
for m in members:
sig = member_signature(m)
mloc = m.find("location")
link = src_link(mloc) if mloc is not None else ""
lines.append(f"### `{sig}`")
if link:
lines.append("")
lines.append(f"📍 {link}")
lines.append("")
mbrief, _, _, _ = render_description(m.find("briefdescription"))
mdetail, params, returns, throws = render_description(m.find("detaileddescription"))
if mbrief:
lines.append(mbrief)
lines.append("")
if mdetail:
lines.append(mdetail)
lines.append("")
if params:
lines.append("**Parameters**")
lines.append("")
for pname, pdesc in params:
lines.append(f"- `{pname}` — {pdesc}" if pdesc else f"- `{pname}`")
lines.append("")
if returns:
lines.append("**Returns** " + " ".join(returns))
lines.append("")
if throws:
lines.append("**Throws**")
lines.append("")
for tname, tdesc in throws:
lines.append(f"- `{tname}` — {tdesc}" if tdesc else f"- `{tname}`")
lines.append("")
lines.append("---")
lines.append("")
lines.append("← [Back to classes](index.md) · [Top](../index.md)")
out_path.write_text("\n".join(lines).rstrip() + "\n")
def emit_file(xml_dir: Path, out_dir: Path, refid: str) -> None:
tree = ET.parse(xml_dir / f"{refid}.xml")
root = tree.find("compounddef")
if root is None:
return
name = (root.findtext("compoundname") or "").strip()
safe = refid # already a flat identifier like system_2modules_8hpp
out_path = out_dir / "files" / f"{safe}.md"
lines: list[str] = []
lines.append(f"# {name}")
lines.append("")
loc = root.find("location")
if loc is not None and loc.attrib.get("file"):
lines.append(f"Source: {src_link(loc)}")
lines.append("")
brief, _, _, _ = render_description(root.find("briefdescription"))
if brief:
lines.append(brief)
lines.append("")
detailed, _, _, _ = render_description(root.find("detaileddescription"))
if detailed:
lines.append(detailed)
lines.append("")
# Inner compounds (classes/structs/namespaces defined in this file).
inner = [(c.attrib.get("refid", ""), (c.text or "").strip())
for c in root.findall("innerclass")]
if inner:
lines.append("## Defines")
lines.append("")
for rid, label in inner:
lines.append(f"- {ref_to_md(rid, label)}")
lines.append("")
# Free functions, variables, typedefs at file scope.
for sec in root.findall("sectiondef"):
sk = sec.attrib.get("kind", "")
title_map = {
"func": "Free Functions",
"var": "Variables",
"typedef": "Typedefs",
"enum": "Enums",
"define": "Macros",
}
title = title_map.get(sk)
if not title:
continue
members = sec.findall("memberdef")
if not members:
continue
lines.append(f"## {title}")
lines.append("")
for m in members:
sig = member_signature(m)
mloc = m.find("location")
link = src_link(mloc) if mloc is not None else ""
lines.append(f"### `{sig}`")
if link:
lines.append("")
lines.append(f"📍 {link}")
lines.append("")
mbrief, _, _, _ = render_description(m.find("briefdescription"))
mdetail, params, returns, throws = render_description(m.find("detaileddescription"))
if mbrief:
lines.append(mbrief); lines.append("")
if mdetail:
lines.append(mdetail); lines.append("")
if params:
lines.append("**Parameters**"); lines.append("")
for pname, pdesc in params:
lines.append(f"- `{pname}` — {pdesc}" if pdesc else f"- `{pname}`")
lines.append("")
if returns:
lines.append("**Returns** " + " ".join(returns)); lines.append("")
if throws:
lines.append("**Throws**"); lines.append("")
for tname, tdesc in throws:
lines.append(f"- `{tname}` — {tdesc}" if tdesc else f"- `{tname}`")
lines.append("")
lines.append("---")
lines.append("")
lines.append("← [Back to files](index.md) · [Top](../index.md)")
out_path.write_text("\n".join(lines).rstrip() + "\n")
# ----------------------------------------------------------------------
# Index pages
# ----------------------------------------------------------------------
def emit_classes_index(out_dir: Path,
entries: list[tuple[str, str, str]]) -> None:
"""entries = list of (refid, name, brief)."""
lines: list[str] = []
lines.append("# Classes & Structs")
lines.append("")
lines.append("| Name | Brief |")
lines.append("|---|---|")
for refid, name, brief in sorted(entries, key=lambda e: e[1].lower()):
m = CLASS_REFID_RE.match(refid)
path = f"{m.group(2)}.md" if m else refid
lines.append(f"| [`{name}`]({path}) | {brief.replace('|', '\\|').strip() or '—'} |")
lines.append("")
lines.append("← [Top](../index.md)")
(out_dir / "classes" / "index.md").write_text("\n".join(lines) + "\n")
def emit_files_index(out_dir: Path,
entries: list[tuple[str, str, str]]) -> None:
lines: list[str] = []
lines.append("# Source Files")
lines.append("")
lines.append("| Path | Brief |")
lines.append("|---|---|")
for refid, name, brief in sorted(entries, key=lambda e: e[1].lower()):
lines.append(f"| [`{name}`]({refid}.md) | {brief.replace('|', '\\|').strip() or '—'} |")
lines.append("")
lines.append("← [Top](../index.md)")
(out_dir / "files" / "index.md").write_text("\n".join(lines) + "\n")
def emit_top_index(out_dir: Path, n_classes: int, n_files: int) -> None:
lines: list[str] = [
"# essim API reference",
"",
"Auto-generated from Doxygen comments in `src/`. Regenerate with",
"`cmake --build build --target doc`. See [doc/README.md](../README.md)",
"for the toolchain.",
"",
f"- [Classes & Structs](classes/index.md) — {n_classes} entries",
f"- [Source Files](files/index.md) — {n_files} entries",
"",
"## Curated reading order",
"",
"Start with the domain model, then importers, then the TUI:",
"",
"1. [`System`](classes/System.md) — owns Modules + Connections.",
"2. [`Module`](classes/Module.md) → [`Part`](classes/Part.md) → "
"[`Pin`](classes/Pin.md) → [`Signal`](classes/Signal.md) — ownership chain.",
"3. [`Connection`](classes/Connection.md) — cross-module wiring with `pin_map`.",
"4. [`Transform`](classes/Transform.md) / "
"[`IdentityTransform`](classes/IdentityTransform.md) — connector-pair → pin pairs.",
"5. [`ImportBase`](classes/ImportBase.md) → "
"[`ImportMentor`](classes/ImportMentor.md), "
"[`ImportAltium`](classes/ImportAltium.md), "
"[`ImportOds`](classes/ImportOds.md) — netlist parsers.",
"6. [`Tui`](classes/Tui.md) — interactive shell + screen orchestration.",
"",
]
(out_dir / "index.md").write_text("\n".join(lines) + "\n")
# ----------------------------------------------------------------------
# Main
# ----------------------------------------------------------------------
def main() -> int:
if len(sys.argv) != 3:
print(__doc__, file=sys.stderr)
return 2
xml_dir = Path(sys.argv[1])
out_dir = Path(sys.argv[2])
if not xml_dir.is_dir():
print(f"xml_dir not found: {xml_dir}", file=sys.stderr)
return 1
out_dir.mkdir(parents=True, exist_ok=True)
(out_dir / "classes").mkdir(exist_ok=True)
(out_dir / "files").mkdir(exist_ok=True)
index = ET.parse(xml_dir / "index.xml").getroot()
classes: list[tuple[str, str, str]] = [] # (refid, name, brief)
files: list[tuple[str, str, str]] = []
for c in index.findall("compound"):
kind = c.attrib.get("kind", "")
refid = c.attrib.get("refid", "")
name = (c.findtext("name") or "").strip()
if kind in ("class", "struct"):
# Read brief from the per-compound XML.
try:
tree = ET.parse(xml_dir / f"{refid}.xml").getroot().find("compounddef")
brief, _, _, _ = render_description(tree.find("briefdescription")) if tree is not None else ("", [], [], [])
except (FileNotFoundError, ET.ParseError):
brief = ""
classes.append((refid, name, brief))
emit_class(xml_dir, out_dir, refid)
elif kind == "file":
try:
tree = ET.parse(xml_dir / f"{refid}.xml").getroot().find("compounddef")
brief, _, _, _ = render_description(tree.find("briefdescription")) if tree is not None else ("", [], [], [])
except (FileNotFoundError, ET.ParseError):
brief = ""
files.append((refid, name, brief))
emit_file(xml_dir, out_dir, refid)
emit_classes_index(out_dir, classes)
emit_files_index(out_dir, files)
emit_top_index(out_dir, len(classes), len(files))
print(f"Wrote {len(classes)} class page(s) and {len(files)} file page(s) "
f"to {out_dir}")
return 0
if __name__ == "__main__":
sys.exit(main())