Developer documentation - #358
Open
MichielTukker wants to merge 22 commits into
Open
Conversation
Contributor
There was a problem hiding this comment.
Pull request overview
This PR restructures and expands developer-focused documentation for OMOTES.SIMULATOR_CORE by adding new contributor guides and updating the documentation-agent workflow, while also removing older reference/architecture documentation pages.
Changes:
- Added several new contributor guides under
doc/developer/(simulation flow, testing, extension workflows, AI-assisted documentation workflow). - Updated documentation-agent definitions to introduce an
RstSyntaxAgentand adjust review/validation routing. - Adjusted many autogenerated API
.rstpages (but these are regenerated during Sphinx builds).
Reviewed changes
Copilot reviewed 115 out of 115 changed files in this pull request and generated 10 comments.
Show a summary per file
| File | Description |
|---|---|
| doc/reference/solver_uncovered_entities.rst | Removes solver supporting-entities reference landing page. |
| doc/reference/solver_reference.rst | Removes curated solver reference landing page. |
| doc/reference/controller_uncovered_entities.rst | Removes controller supporting-entities reference landing page. |
| doc/reference/controller_reference.rst | Removes curated controller reference landing page. |
| doc/reference/asset_uncovered_entities.rst | Removes asset supporting-entities reference landing page. |
| doc/reference/asset_reference.rst | Removes curated asset reference landing page. |
| doc/reference/architecture_reference.rst | Removes curated architecture reference landing page. |
| doc/developer/writing_documentation_with_ai.rst | Adds contributor guide for the AI-agent documentation workflow. |
| doc/developer/testing.rst | Adds contributor guide describing test layout and how to run tests. |
| doc/developer/simulation_contributor_flow.rst | Adds end-to-end “where to change what” execution-flow guide for contributors. |
| doc/developer/developer_navigation.rst | Reworks developer navigation to point to the new contributor guides. |
| doc/developer/developer_main.rst | Updates Developer Documentation landing page and its toctree to the new guides. |
| doc/developer/control_extension.rst | Adds step-by-step guide for extending controller behavior. |
| doc/developer/add_new_output_format.rst | Adds step-by-step guide for extending simulator output. |
| doc/developer/add_new_asset.rst | Adds step-by-step guide for implementing a new physics asset. |
| doc/developer/api/omotes_simulator_core.solver.solver.rst | Adjusts automodule options formatting in generated API doc output. |
| doc/developer/api/omotes_simulator_core.solver.solver_constants.rst | Adjusts automodule options formatting in generated API doc output. |
| doc/developer/api/omotes_simulator_core.solver.rst | Adjusts automodule options formatting in generated API doc output. |
| doc/developer/api/omotes_simulator_core.solver.network.rst | Adjusts automodule options formatting in generated API doc output. |
| doc/developer/api/omotes_simulator_core.solver.network.network.rst | Adjusts automodule options formatting in generated API doc output. |
| doc/developer/api/omotes_simulator_core.solver.network.assets.solver_pipe.rst | Adjusts automodule options formatting in generated API doc output. |
| doc/developer/api/omotes_simulator_core.solver.network.assets.rst | Adjusts automodule options formatting in generated API doc output. |
| doc/developer/api/omotes_simulator_core.solver.network.assets.production_asset.rst | Adjusts automodule options formatting in generated API doc output. |
| doc/developer/api/omotes_simulator_core.solver.network.assets.node.rst | Adjusts automodule options formatting in generated API doc output. |
| doc/developer/api/omotes_simulator_core.solver.network.assets.heat_transfer_asset.rst | Adjusts automodule options formatting in generated API doc output. |
| doc/developer/api/omotes_simulator_core.solver.network.assets.fall_type.rst | Adjusts automodule options formatting in generated API doc output. |
| doc/developer/api/omotes_simulator_core.solver.network.assets.buffer_asset.rst | Adjusts automodule options formatting in generated API doc output. |
| doc/developer/api/omotes_simulator_core.solver.network.assets.boundary.rst | Adjusts automodule options formatting in generated API doc output. |
| doc/developer/api/omotes_simulator_core.solver.network.assets.base_node_item.rst | Adjusts automodule options formatting in generated API doc output. |
| doc/developer/api/omotes_simulator_core.solver.network.assets.base_item.rst | Adjusts automodule options formatting in generated API doc output. |
| doc/developer/api/omotes_simulator_core.solver.network.assets.base_asset.rst | Adjusts automodule options formatting in generated API doc output. |
| doc/developer/api/omotes_simulator_core.solver.network.assets.air_to_water_heat_pump.rst | Adjusts automodule options formatting in generated API doc output. |
| doc/developer/api/omotes_simulator_core.solver.matrix.rst | Adjusts automodule options formatting in generated API doc output. |
| doc/developer/api/omotes_simulator_core.solver.matrix.matrix.rst | Adjusts automodule options formatting in generated API doc output. |
| doc/developer/api/omotes_simulator_core.solver.matrix.index_core_quantity.rst | Adjusts automodule options formatting in generated API doc output. |
| doc/developer/api/omotes_simulator_core.solver.matrix.equation_object.rst | Adjusts automodule options formatting in generated API doc output. |
| doc/developer/api/omotes_simulator_core.simulation.rst | Adjusts automodule options formatting in generated API doc output. |
| doc/developer/api/omotes_simulator_core.simulation.networksimulation.rst | Adjusts automodule options formatting in generated API doc output. |
| doc/developer/api/omotes_simulator_core.simulation.mappers.rst | Adjusts automodule options formatting in generated API doc output. |
| doc/developer/api/omotes_simulator_core.simulation.mappers.mappers.rst | Adjusts automodule options formatting in generated API doc output. |
| doc/developer/api/omotes_simulator_core.rst | Adjusts automodule options formatting in generated API doc output. |
| doc/developer/api/omotes_simulator_core.infrastructure.utils.rst | Adjusts automodule options formatting in generated API doc output. |
| doc/developer/api/omotes_simulator_core.infrastructure.simulation_manager.rst | Adjusts automodule options formatting in generated API doc output. |
| doc/developer/api/omotes_simulator_core.infrastructure.rst | Adjusts automodule options formatting in generated API doc output. |
| doc/developer/api/omotes_simulator_core.infrastructure.profiling.rst | Adjusts automodule options formatting in generated API doc output. |
| doc/developer/api/omotes_simulator_core.infrastructure.plotting.rst | Adjusts automodule options formatting in generated API doc output. |
| doc/developer/api/omotes_simulator_core.infrastructure.app.rst | Adjusts automodule options formatting in generated API doc output. |
| doc/developer/api/omotes_simulator_core.entities.utility.rst | Adjusts automodule options formatting in generated API doc output. |
| doc/developer/api/omotes_simulator_core.entities.utility.influxdb_reader.rst | Adjusts automodule options formatting in generated API doc output. |
| doc/developer/api/omotes_simulator_core.entities.simulation_configuration.rst | Adjusts automodule options formatting in generated API doc output. |
| doc/developer/api/omotes_simulator_core.entities.rst | Adjusts automodule options formatting in generated API doc output. |
| doc/developer/api/omotes_simulator_core.entities.network_controller.rst | Adjusts automodule options formatting in generated API doc output. |
| doc/developer/api/omotes_simulator_core.entities.network_controller_abstract.rst | Adjusts automodule options formatting in generated API doc output. |
| doc/developer/api/omotes_simulator_core.entities.heat_network.rst | Adjusts automodule options formatting in generated API doc output. |
| doc/developer/api/omotes_simulator_core.entities.esdl_object.rst | Adjusts automodule options formatting in generated API doc output. |
| doc/developer/api/omotes_simulator_core.entities.assets.utils.rst | Adjusts automodule options formatting in generated API doc output. |
| doc/developer/api/omotes_simulator_core.entities.assets.rst | Adjusts automodule options formatting in generated API doc output. |
| doc/developer/api/omotes_simulator_core.entities.assets.pyjnius_loader.rst | Adjusts automodule options formatting in generated API doc output. |
| doc/developer/api/omotes_simulator_core.entities.assets.production_cluster.rst | Adjusts automodule options formatting in generated API doc output. |
| doc/developer/api/omotes_simulator_core.entities.assets.pipe.rst | Adjusts automodule options formatting in generated API doc output. |
| doc/developer/api/omotes_simulator_core.entities.assets.junction.rst | Adjusts automodule options formatting in generated API doc output. |
| doc/developer/api/omotes_simulator_core.entities.assets.ideal_heat_storage.rst | Adjusts automodule options formatting in generated API doc output. |
| doc/developer/api/omotes_simulator_core.entities.assets.heat_pump.rst | Adjusts automodule options formatting in generated API doc output. |
| doc/developer/api/omotes_simulator_core.entities.assets.heat_exchanger.rst | Adjusts automodule options formatting in generated API doc output. |
| doc/developer/api/omotes_simulator_core.entities.assets.esdl_asset_object.rst | Adjusts automodule options formatting in generated API doc output. |
| doc/developer/api/omotes_simulator_core.entities.assets.demand_cluster.rst | Adjusts automodule options formatting in generated API doc output. |
| doc/developer/api/omotes_simulator_core.entities.assets.controller.temperature_data.rst | Adjusts automodule options formatting in generated API doc output. |
| doc/developer/api/omotes_simulator_core.entities.assets.controller.rst | Adjusts automodule options formatting in generated API doc output. |
| doc/developer/api/omotes_simulator_core.entities.assets.controller.profile_interpolation.rst | Adjusts automodule options formatting in generated API doc output. |
| doc/developer/api/omotes_simulator_core.entities.assets.controller.controller_storage.rst | Adjusts automodule options formatting in generated API doc output. |
| doc/developer/api/omotes_simulator_core.entities.assets.controller.controller_producer.rst | Adjusts automodule options formatting in generated API doc output. |
| doc/developer/api/omotes_simulator_core.entities.assets.controller.controller_network.rst | Adjusts automodule options formatting in generated API doc output. |
| doc/developer/api/omotes_simulator_core.entities.assets.controller.controller_heat_transfer.rst | Adjusts automodule options formatting in generated API doc output. |
| doc/developer/api/omotes_simulator_core.entities.assets.controller.controller_consumer.rst | Adjusts automodule options formatting in generated API doc output. |
| doc/developer/api/omotes_simulator_core.entities.assets.controller.asset_controller_abstract.rst | Adjusts automodule options formatting in generated API doc output. |
| doc/developer/api/omotes_simulator_core.entities.assets.ates_cluster.rst | Adjusts automodule options formatting in generated API doc output. |
| doc/developer/api/omotes_simulator_core.entities.assets.asset_defaults.rst | Adjusts automodule options formatting in generated API doc output. |
| doc/developer/api/omotes_simulator_core.entities.assets.asset_abstract.rst | Adjusts automodule options formatting in generated API doc output. |
| doc/developer/api/omotes_simulator_core.entities.assets.air_to_water_heat_pump.rst | Adjusts automodule options formatting in generated API doc output. |
| doc/developer/api/omotes_simulator_core.adapter.utility.rst | Adjusts automodule options formatting in generated API doc output. |
| doc/developer/api/omotes_simulator_core.adapter.utility.graph.rst | Adjusts automodule options formatting in generated API doc output. |
| doc/developer/api/omotes_simulator_core.adapter.transforms.transform_utils.rst | Adjusts automodule options formatting in generated API doc output. |
| doc/developer/api/omotes_simulator_core.adapter.transforms.string_to_esdl.rst | Adjusts automodule options formatting in generated API doc output. |
| doc/developer/api/omotes_simulator_core.adapter.transforms.rst | Adjusts automodule options formatting in generated API doc output. |
| doc/developer/api/omotes_simulator_core.adapter.transforms.mappers.rst | Adjusts automodule options formatting in generated API doc output. |
| doc/developer/api/omotes_simulator_core.adapter.transforms.esdl_graph_mapper.rst | Adjusts automodule options formatting in generated API doc output. |
| doc/developer/api/omotes_simulator_core.adapter.transforms.esdl_asset_mappers.rst | Adjusts automodule options formatting in generated API doc output. |
| doc/developer/api/omotes_simulator_core.adapter.transforms.esdl_asset_mappers.producer_mapper.rst | Adjusts automodule options formatting in generated API doc output. |
| doc/developer/api/omotes_simulator_core.adapter.transforms.esdl_asset_mappers.pipe_mapper.rst | Adjusts automodule options formatting in generated API doc output. |
| doc/developer/api/omotes_simulator_core.adapter.transforms.esdl_asset_mappers.ideal_heat_storage_mapper.rst | Adjusts automodule options formatting in generated API doc output. |
| doc/developer/api/omotes_simulator_core.adapter.transforms.esdl_asset_mappers.heat_pump_mapper.rst | Adjusts automodule options formatting in generated API doc output. |
| doc/developer/api/omotes_simulator_core.adapter.transforms.esdl_asset_mappers.heat_exchanger_mapper.rst | Adjusts automodule options formatting in generated API doc output. |
| doc/developer/api/omotes_simulator_core.adapter.transforms.esdl_asset_mappers.consumer_mapper.rst | Adjusts automodule options formatting in generated API doc output. |
| doc/developer/api/omotes_simulator_core.adapter.transforms.esdl_asset_mappers.ates_mapper.rst | Adjusts automodule options formatting in generated API doc output. |
| doc/developer/api/omotes_simulator_core.adapter.transforms.esdl_asset_mapper.rst | Adjusts automodule options formatting in generated API doc output. |
| doc/developer/api/omotes_simulator_core.adapter.transforms.controller_mappers.rst | Adjusts automodule options formatting in generated API doc output. |
| doc/developer/api/omotes_simulator_core.adapter.transforms.controller_mappers.controller_storage_mapper.rst | Adjusts automodule options formatting in generated API doc output. |
| doc/developer/api/omotes_simulator_core.adapter.transforms.controller_mappers.controller_producer_mapper.rst | Adjusts automodule options formatting in generated API doc output. |
| doc/developer/api/omotes_simulator_core.adapter.transforms.controller_mappers.controller_heat_transfer_mapper.rst | Adjusts automodule options formatting in generated API doc output. |
| doc/developer/api/omotes_simulator_core.adapter.transforms.controller_mappers.controller_consumer_mapper.rst | Adjusts automodule options formatting in generated API doc output. |
| doc/developer/api/omotes_simulator_core.adapter.transforms.controller_mapper.rst | Adjusts automodule options formatting in generated API doc output. |
| doc/developer/api/omotes_simulator_core.adapter.rst | Adjusts automodule options formatting in generated API doc output. |
| doc/developer/api/omotes_simulator_core.adapter.presentation.rst | Adjusts automodule options formatting in generated API doc output. |
| doc/architecture/simulation_manager.rst | Removes older architecture autodoc page for SimulationManager. |
| doc/architecture/network_simulation.rst | Removes older architecture autodoc page for NetworkSimulation. |
| doc/architecture/esdl_object.rst | Removes older architecture autodoc page for EsdlObject. |
| doc/architecture/esdl_asset_object.rst | Removes older architecture autodoc page for EsdlAssetObject. |
| doc/architecture/configuration.rst | Removes older architecture autodoc page for SimulationConfiguration. |
| doc/architecture/asset_factories.rst | Removes older contributor-facing map of ESDL asset factory layer. |
| doc/architecture/architecture.rst | Removes older “General architecture” landing page. |
| .github/agents/SphinxValidationAgent.agent.md | Extends validation routing to include RstSyntaxAgent. |
| .github/agents/RstSyntaxAgent.agent.md | Adds a new agent definition for RST syntax/format validation. |
| .github/agents/DocumentationCoordinator.agent.md | Updates coordinator agent list to include RstSyntaxAgent. |
| .github/agents/DocReviewAgent.agent.md | Updates review rules to explicitly cover developer guide review expectations. |
| .github/agents/DeveloperGuideAgent.agent.md | Updates DeveloperGuideAgent prompt guidance and section requirements. |
… for building documentation (missing crossplatform script)
Comment on lines
+11
to
+15
| if command -v python3 >/dev/null 2>&1; then | ||
| python3 -m venv .venv | ||
| elif command -v python >/dev/null 2>&1; then | ||
| python -m venv .venv | ||
| else |
Comment on lines
15
to
19
| .. toctree:: | ||
| :maxdepth: 1 | ||
| :titlesonly: | ||
|
|
||
| developer_navigation |
samvanderzwan
requested changes
Sep 10, 2026
| The dependency direction is one-way: the entity layer depends on the solver layer. Solver-layer | ||
| classes must never import from ``entities/``. | ||
|
|
||
| Control Architecture |
Contributor
There was a problem hiding this comment.
I am missing short description that user can also add its own control be adding a new Networkcontroller class which inheritant from the abstract class.
Also the first line it does not sits between. It defines the setpoints for the heatnetwork.
|
|
||
| The control layer sits between ``NetworkSimulation`` and ``HeatNetwork``: | ||
|
|
||
| - ``NetworkControllerAbstract`` defines the contract: one abstract method, |
Contributor
There was a problem hiding this comment.
What is meant with contract?
| - Maps ESDL asset types to per-asset mapper classes via ``conversion_dict_mappers``. | ||
| * - ``unit_test/infrastructure/test_simulationmanager.py`` | ||
| - Orchestration unit tests | ||
| - Verifies ``SimulationManager.execute`` returns output and triggers the progress |
Contributor
There was a problem hiding this comment.
Why add the unit test here? and only a couple
| ~~~~~~~~~~~~~ | ||
|
|
||
| Mapper tests live in ``unit_test/adapters/``. The main file is | ||
| ``unit_test/adapters/test_esdl_graph_mapper.py``. Mapper tests verify that a known ESDL |
Contributor
There was a problem hiding this comment.
File location is incorrect as that this is the main file
| name=asset_name, | ||
| _id=asset_id, | ||
| ) | ||
| self._register_solver_asset(self.solver_asset) |
Contributor
There was a problem hiding this comment.
This method does not exist at all
| @@ -0,0 +1,230 @@ | |||
| Adding New Solver and Entity Layer Assets | |||
Contributor
There was a problem hiding this comment.
This is partly a repeat of Add ENtityLayerAsset. So better to reference to that
| dispatch: update network state, calculate per-network totals, distribute demand across | ||
| producers, and return the setpoints dict. | ||
|
|
||
| **Abstract contract** (``entities/network_controller_abstract.py``) |
Contributor
There was a problem hiding this comment.
Would not call it contract
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
First attempt at developer documentation.
I've reviewed the scope and process of the docs, which are good enough for now. The documentation describes all requested parts (architecture, quick how-to's, testing, documentation, api-doc).
This PR also includes a new agent: RstSyntaxAgent it's goal is to validate the RST syntax as I had some issues with the sphinx validation agent. The RstSyntaxAgent calls some specific Sphinx commands for Rst validation, so it should be reliable.