Feature uml diagram

[PXY-no]

Fixes #52

This pull request adds a UML class diagram to the main documentation page to help developers understand the project's code architecture.

Key Changes

UML Generation with Mermaid

• Added a new make uml command to generate a .mmd UML class diagram from the Python source code using pyreverse.
• mermaidx is used to convert the generated Mermaid diagram into an SVG, which is included in docs/index.md.
• As an alternative, the .mmd file can be rendered directly in MkDocs using Mermaid, pymdownx.snippets and pymdownx.superfences.

CI

• Added a GitHub Actions workflow for the SVG-based approach that regenerates the UML diagram and checks whether the committed SVG is up to date.
• This helps prevent the diagram from becoming outdated when the source code changes.

Comparison

The following comparison highlights the main differences between the approaches, including the generation workflow, dependencies and integration into MkDocs.

• pyreverse + Graphviz: pyreverse generates the .dot file, which is then rendered to PNG using Graphviz's dot command. The resulting PNG is embedded in MKDocs. This approach requires Graphviz to be installed as a system dependency.
• pyreverse + mermaidx: pyreverse generates a .mmd file, which is then converted to SVG using mermaidx. The resulting SVG is embedded in MKDocs. mermaidx can be managed as a Poetry dependency.
• Mermaid directly in MkDocs: pyreverse generates a .mmd file, which is included in a Mermaid code block using pymdownx.snippets and rendered by MkDocs with pymdownx.superfences. The resulting diagram is displayed directly in the MkDocs documentation and can be styled using Mermaid or CSS.

Screenshots are included below showing the generated UML as a local file and as part of the MkDocs documentation.

• Tests pass
• Appropriate changes to documentation are included in the PR

[s2t2]

Thanks @PXY-no

I'm concerned the diagram is too large to comprehend. I wonder what other formatting options we have to control the level of detail.

I also wonder if it might be better to create separate diagrams for the different parts / modules of the codebase.

Let me know what you think.

Also I see there is a conflic with the poetry lock file that needs to be fixed.

[PXY-no]

I agree that the current diagram is quite large and can be difficult to comprehend.

The diagram currently includes the entire smart_control codebase, including *_test.py files. I wasn't sure whether we should include the test classes or exclude them from the diagram, as both approaches could make sense depending on what we want the diagram to represent.

Instead of splitting it into separate diagrams and potentially losing relationships between modules, I found mkdocs-panzoom, which adds pan and zoom functionality to the diagram. This allows us to keep the architecture in a single diagram while making it easier to navigate.

I've attached some screenshots showing the normal view, zoomed-in view and horizontal panning. I also tried removing the test classes from the UML diagram to see how this affects readability.

What do you think?