# tools/generators/ — the new generator code

Maintainer tools around [`definitions/`](../../definitions/README.md), the input of code
generation, and all code generators: the driver `generate.py`, the emitters,
their shared helpers (`autoGenerateHelper.py`, `generatorPaths.py`), `createStubFiles.py` with
`stubHeader.pyi`, and `generated/`, the intermediate files handed from one stage to the next.
`src/pythonGenerator/` is gone; `exudynVersion.py`, which the
build reads, lives here. `doc2rst.py` and
`latexConverter.py` were deleted What stood here before:
`makeAllBinariesScripts.py` and `exudynVersion.py` (read by `setup.py` and `conf.py`).

| file | what it does | used by |
|---|---|---|
| `definitionLoader.py` | imports `definitions/` and hands each class to the generators as `(parseInfo, parameterList)` - the form their old line parser produced - so their per-class code is unchanged. Removed once the generators read `definitions/` directly | `itemModel.LegacyItems()`, `structureModel.LegacyStructures()` |
| `typeModel.py` | one type model: `Render(typeName, destination, context)` spells a definition type for `cppStorage`, `cppExchange`, `dictType`, `stub` or `pyTyping`, for items or structures; rules plus a named exception table | the item and structure emitters, `definitionValidator.py` |
| `itemModel.py` | facts about items shared by the emitters: type predicates, user-function types, member predicates for direct access (`IsOwnVariable`, `HasFlag`, `DefaultValue`, ...), how a `definitions/` member renders to the old string forms, per-item accessors | the item emitters, `definitionLoader.py` |
| `itemInterfaceEmitter.py` | emits `python/exudyn/itemInterface.py` from `definitions/`; `--output` for another target | `tools/regenerate.py` |
| `itemHeaderEmitter.py` | emits the per-item C++ headers `C/Main/Visu<Item>.h`, `PySymbolicUserFunctionSet.h` / `PythonUserFunctionsTemplates.h` and `objectFactoryAutoReg.h`; `--output-dir` for another target | `tools/regenerate.py` |
| `miniExampleEmitter.py` | emits `python/MiniExamples/<Item>.py` and `miniExamplesFileList.py`; `--output-dir` | `tools/regenerate.py` |
| `itemDocsEmitter.py` | emits the item reference manual: `docs/generated/items/*.md` (one page per item, one index per item type) and `confHelperItems.py` | `tools/regenerate.py` |
| `structureModel.py` | facts about structures shared by the structure emitters: type tables, predicates on classes and parameters, sorted parameters, typical paths, the old string records | the structure emitters |
| `structureHeaderEmitter.py` | emits the structure C++ headers (`SimulationSettings.h`, `VisualizationSettings.h`, ...), `DictionariesGetSet.h` and `pybind_modules.h` | `tools/regenerate.py` |
| `structureStubEmitter.py` | emits the stub fragment `tools/generators/generated/stubSystemStructures.pyi` read by `createStubFiles.py` | `tools/regenerate.py` |
| `structureDocsEmitter.py` | emits the structure reference documentation: `docs/generated/structures/*.md` | `tools/regenerate.py` |
| `examplesDocsEmitter.py` | emits the pages of `python/Examples/` and `python/TestModels/`, and `docs/generated/abbreviations.md` | `tools/regenerate.py` |
| `latexToMarkdown.py` | the LaTeX of `definitions/` and of the docstrings, as MyST Markdown; called by every docs emitter | the emitters |
| `docstringText.py` | text helpers for generated docstrings (`RemoveIndentation`, `CleanStringForPyiDescription`, `SplitSummaryDescription`) and `GoogleDocstringRenderer`; what was kept of `autoGenerateDocstrings.py` | `autoGenerateHelper.py`, `itemInterfaceEmitter.py` |
| `enumEmitter.py` | generates `src/Autogenerated/EnumTypes.h` (enums and string functions) from `definitions/enumTypes.py`, after checking unique names and values | `pybindEmitter.py`, on every generation |
| `utilityDocsModel.py` | the reader of the docstrings in the utility modules, with `ast` (statically; `@docmeta` gives author, date, status and `public=False`, `@extends(exudyn.MainSystem)` a MainSystem method) and the text helpers shared by the three emitters below | the utility emitters |
| `mainSystemExtensionDocsEmitter.py` | emits `MainSystemExt`/`MainSystemCreateExt` as `.md` and `.rst` fragments for the `@extends` functions (both read by `pybindEmitter.py`) and `stubAutoBindingsExt.pyi` | `tools/regenerate.py`, before `pybindEmitter.py` |
| `utilityDocsEmitter.py` | emits the utility module reference: `docs/generated/pythonUtilities/*.md` and `confHelperPyUtilities.py` | `tools/regenerate.py` |
| `pybindEmitter.py` | replays `definitions/pybind*.py` into `pybind_manual_classes.h`, the stub fragments `stubAutoBindings.pyi` / `stubSymbolic.pyi` / `stubEnums.pyi`, `docs/generated/cInterface/*.md` and `confHelper.py` | `tools/regenerate.py` |
| `generate.py` | the single driver: declares every generator stage with the paths it reads and writes, derives the run order, validates `definitions/` first; `--list`, `--only NAME` | `tools/regenerate.py`, or directly |
| `definitionValidator.py` | the cross-file checks on `definitions/`: every virtual item function overrides a real declaration in the C++ parent headers, `fromParent` members exist in the parent, no duplicate member, shaped defaults have the right size, a body declares an access function type exactly if it provides its function (#2744); in `pybind*.py`, argument/default/type lists agree, no function is declared twice, Begin/End steering calls pair up; reports all violations | `tools/regenerate.py`, before the generators run (exit code 3) |
| `outputVariableEmitter.py` | generates `src/Autogenerated/OutputVariableTypes.h` from `definitions/outputVariableTypes.py`, after checking the bit allocation | `pybindEmitter.py`, on every generation |

## Changing a definition

Edit `definitions/`, then in `venvExuP313`:

```
python tools/regenerate.py --check
```

It validates the definitions, runs all generators and reports what changed in the generated set.