Developer documentation #358
Open
MichielTukker wants to merge 20 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 |
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.