[FEATURE] Autogenerate class/module diagrams for Python

[mgovers]

Use pyreverse (distributed together with pylint by default) to create module graph and class diagram

• Create a module graph of the python library
• Create a class diagram of the Python library in the github action that generates the documentation
• Add to the documentation generation action in https://github.com/PowerGridModel/power-grid-model/blob/main/.readthedocs.yaml
• Include in the advanced documentation
  • Please create a new page docs/advanced_documentation/python-wrapper-design.md that contains a small introduction + the diagrams.
  • Add the new page to the the docs/index.md part on Advanced Documentation.
  • NOTE: We have docs/advanced_documentation/core-design.md but that only talks about the design of the C API core. Therefore, that is not the right location to put it.

Relates to #749 and #525

[emabre]

Hi, I would like to begin contributing to this project and this issue seems to be a good candidate to start with. Is this issue still needed and up to date?

If it's needed, a couple of questions on the diagrams:

• I noticed that the diagram of the classes that gets generated by pyreverse is very crowded. Should I prune it or hide some details somehow? See the images that I attached (I know there are some things to fix in those diagrams, it's just to give an idea).
• What format should be used for the diagrams, I guess SVG, right?

Classes diagram:

Module diagram

Thanks

[mgovers]

Hi @emabre ,

Great to hear you are willing to pick this up!

Is this issue still needed and up to date?

The issue still seems to be up-to-date, indeed. I will make some decisions on where in the docs to add the graph and update the description.

I noticed that the diagram of the classes that gets generated by pyreverse is very crowded. Should I prune it or hide some details somehow? See the images that I attached (I know there are some things to fix in those diagrams, it's just to give an idea).

I think pruning is a good idea. There are multiple ways to do that (e.g., splitting up into smaller diagrams, removing details, ...). Any improvement is already a huge one, so I will leave that up to you. If you prefer, you can also send an email to martijn.govers@alliander.com, and we can briefly talk about the options)

What format should be used for the diagrams, I guess SVG, right?

I also think that SVG is indeed the way to go, but I am not an expert on this. Note that we already have some graphs embedded into the docs using mermaid (see, e.g., https://power-grid-model.readthedocs.io/en/stable/advanced_documentation/core-design.html#calculation-logic-and-data-flow), but those are not auto-generated. Using SVG, you can embed the graph as an image, but if you have a better way of doing that, we are also open to input.

Hope that helps! If you have any other questions, feel free to ask them here, on a draft PR, or otherwise contact me directly via martijn.govers@alliander.com

Martijn

[emabre]

@mgovers thank you very much for your reply. I'll reach out in case I have further questions.
Thanks,
Ema