[FEATURE] Generate component attributes documentation using code generator

[mgovers]

Currently, several files are generated by the code generator in https://github.com/PowerGridModel/power-grid-model/tree/main/code_generation .

However, there is component documentation based on that generated code in https://power-grid-model.readthedocs.io/en/stable/user_manual/components.html that is manually created. This documentation can go out of date without anyone noticing, e.g. because default values changing.

This ticket is about generating the component documentation via the code generator.

TODO

• [ ] Combine https://github.com/PowerGridModel/power-grid-model/blob/main/code_generation/data/attribute_classes/input.json and https://github.com/PowerGridModel/power-grid-model/blob/main/code_generation/data/attribute_classes/update.json into single configuration file:
  • All attributes in update.json are also present in input.json
  • Therefore, the combined configuration file can generate equivalently loaded input.json-like and update.json-like data based on a boolean flag is_updateable: true, e.g.

{
    "name": "input",
    "include_guard": "INPUT",
    "classes": [
        {
            "name": "BranchInput",
            "base": "BaseInput",
            "attributes": [
                {
                    "data_type": "ID",
                    "names": [
                        "from_node",
                        "to_node"
                    ],
                    "description": "node IDs to which this branch is connected at both sides",
                    "is_updateable": false
                },
                {
                    "data_type": "IntS",
                    "names": [
                        "from_status",
                        "to_status"
                    ],
                    "description": "whether the branch is connected at each side",
                    "is_updateable": true
                }
            ]
        }
    ]
}

• [ ] Add fields to both the input.json (or equivalent) and the output.json files with the long description from https://power-grid-model.readthedocs.io/en/stable/user_manual/components.html
  • [ ] both input.json and output.json
    • [ ] unit (- in the docs should be null in the configuration file)
    • [ ] long_description
  • [ ] only input.json
    • [ ] required
    • [ ] valid_values
    • [ ] default_value
• [ ] Add a template to the code generation templates that generates the tables in https://power-grid-model.readthedocs.io/en/stable/user_manual/components.html (but keeps all other content)

TBD

• [ ] How to handle values that are required for some data types but not for others? (e.g. r0 is only required for asymmetric calculations)
• [ ] Should we add an no_docs or experimental flag to make sure that attributes-under-construction are not added to the docs?
• [ ] How to nicely handle multi-field component names (e.g.: from_node and to_node)
  • [ ] Proposed: make "long_description" an array when there are multiple names, just like "names"
• [ ] How to handle hyperlings?
  • Example (taken from https://power-grid-model.readthedocs.io/en/stable/user_manual/components.html#generic-power-sensor ):
    • {hoverxreftooltip}`user_manual/components:Power Sensor Concrete Types`
    • [concrete types](#power-sensor-concrete-types)
  • [ ] Proposed: as long as they don't contain " we can directly keep using them as is
• [ ] Are we still missing something?

Example

{
    "name": "input",
    "include_guard": "INPUT",
    "classes": [
        {
            "name": "BranchInput",
            "base": "BaseInput",
            "attributes": [
                {
                    "data_type": "ID",
                    "names": [
                        "from_node",
                        "to_node"
                    ],
                    "description": "node IDs to which this branch is connected at both sides",
                    "is_updateable": false,
                    "unit":  null,
                    "long_description": [
                        "ID of node at from-side",
                        "ID of node at to-side"
                    ],
                    "required": true,
                    "valid_values": "a valid node ID",
                    "default_value": null
                },
                {
                    "data_type": "IntS",
                    "names": [
                        "from_status",
                        "to_status"
                    ],
                    "description": "whether the branch is connected at each side",
                    "is_updateable": true,
                    "unit":  null,
                    "long_description": [
                        "connection status at from-side",
                        "connection status at to-side"
                    ],
                    "required": true,
                    "valid_values": "`0` or `1`",
                    "default_value": null
                }
            ]
        }
    ]
}