Add Graphical Repo/ Code Base Overview

[MarcoHuebner]

Issue:
Currently, our codebase lacks a comprehensive graphical representation, making it challenging for (irregular) contributors and new developers to understand the overall structure. Introducing software engineering frameworks like class diagrams or data flow charts can significantly enhance the project's documentation and improve the onboarding experience.

Proposed Solution:
Create a graphical code base overview in whatever form suits best, which illustrates the relationships and dependencies between classes as well as paths users (have to) take to receive requested data. This diagram will serve as a high-level guide for developers, making it easier for them to navigate the codebase.

Implementation Steps:

• Research and select a suitable tool for generating such a diagram from code.
• Identify key classes and their relationships within the codebase.
• Generate the diagram.
• [Optional] Include the diagram in the project's documentation, e.g. Wiki and/ or Sphinx.
• [Optional] Update the README to guide contributors on how to interpret and use the class diagram.

[pmayd]

I looked for tools and the only one that I could find and which is free is pycallgraph2.

Sadly, it does not work with modules or libraries, but you have to specify a script that it analyzes, which means for it to work properly, we have to write a small script that executes the functions from pystatis in a meaningful way. To play around with it I just gave it the table.py module:

pycallgraph -i "pystatis.*" graphviz -- src/pystatis/table.py

and this is the result:

I guess this is not so bad and it can follow the function calls and show the dependencies. However, we need to write a proper execution script to see the dependencies clearly

[pmayd]

This is really cool, I just wrote this very small script:

import pystatis

pystatis.set_db("genesis")

t = pystatis.Table("11111-0001")
t.get_data()
t.data
t.metadata
t.name

And the output is much better and more detailed related to Table class:

[MarcoHuebner]

I have no experience in that direction (yet), but the LLM of my trust pointed me to Doxygen ("You can configure doxygen to extract the code structure from undocumented source files. This is very useful to quickly find your way in large source distributions. Doxygen can also visualize the relations between the various elements by means of include dependency graphs, inheritance diagrams, and collaboration diagrams, which are all generated automatically.") and PlantUML for VSCode.

Do you have experience with one of the tools and perhaps already know that they do not work for our purpose?

[MarcoHuebner]

Quick update: I tried PlantUML and it didn't seem to be made for the purpose I thought, doxygen is not straight forward to set up for Windows (skipped for now), but pyreverse -o png -p yourpackage . (comes with pylint, requires graphviz) gave me some results (see below)

and code2flow worked even better (simply running code2flow src/pystatis/*.py - but it misses at least the custom errors from exception.py

Let me know what you think :)