Developer documentation #358
Open
MichielTukker wants to merge 11 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. |
Comment on lines
30
to
+35
| .. toctree:: | ||
| :maxdepth: 1 | ||
| :titlesonly: | ||
|
|
||
| developer_navigation | ||
| ../reference/architecture_reference | ||
| ../reference/asset_reference | ||
| ../reference/solver_reference | ||
| ../reference/controller_reference | ||
| simulation_contributor_flow |
Contributor
Author
There was a problem hiding this comment.
These files will be overwritten by other contributors
Comment on lines
+253
to
+254
| - :doc:`../architecture/network_simulation` — conceptual overview of how the network | ||
| simulation coordinates assets, the solver, and the controller. |
|
|
||
| .. code-block:: console | ||
|
|
||
| .\.venv\Scripts\python -m sphinx -b html doc doc/_build/html |
|
|
||
| .. code-block:: bash | ||
|
|
||
| .\.venv\Scripts\python -m sphinx -b html doc doc/_build/html |
|
|
||
| .. code-block:: bash | ||
|
|
||
| PYTHONPATH='$PYTHONPATH:src/' pytest -p no:faulthandler --junit-xml=test-results.xml unit_test/ |
|
|
||
| Run the test suite from the repository root:: | ||
|
|
||
| PYTHONPATH='$PYTHONPATH:src/' pytest -p no:faulthandler --junit-xml=test-results.xml unit_test/ |
|
|
||
| Developer guide review rules | ||
| ----------------------------- | ||
| Treat developer guides as a distinct documentation type. This section of the documenation has a different audience and purpose than physics documentation. |
| Treat developer guides as a distinct documentation type. This section of the documenation has a different audience and purpose than physics documentation. | ||
| The developer guide section is intended to help contributors understand the codebase, extend it, and test it. It should not be used as a primary source of end-user explanation or conceptual understanding. Review developer guides against these distinctions. | ||
|
|
||
| Flag the followinbg as errors: |
| name: DeveloperGuideAgent | ||
| description: Create contributor-facing developer guide documentation in reStructuredText for SIMULATOR-CORE, covering extension workflows, code navigation, testing practices, and implementation-oriented guidance while keeping narrative guides separate from autogenerated API reference. | ||
| argument-hint: Developer documentation goal, target file, page title, and implementation topic (for example: add a new asset, control extension, simulation flow for contributors, testing strategy). | ||
| argument-hint: Developer documentation goal, target file, page title, and implementation topic (for example: add a new entity-layer asset baed on an existing solver asset, add a new solver asset with and a new entity layer asset, control extension, add a new output format, simulation flow for contributors, testing strategy, writing documentation with the help of ai agents). |
Comment on lines
4
to
+7
| .. automodule:: omotes_simulator_core.solver | ||
| :members: | ||
| :undoc-members: | ||
| :show-inheritance: | ||
| :undoc-members: |
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.