Automatisierte UML-Diagramme auf bo4e.de integrieren

hf-kklein commented 2 years ago

Hi Tim,

@lord-haffi (Leon, unser Werkstudent) hat die automatisierte Erstellung von UML-Diagrammen aus dem Code jetzt soweit abgeschlossen, dass wir damit zufrieden sind. Für die Business Objects bspw. findet ihr einige Diagramme hier: https://bo4e-python.readthedocs.io/en/latest/api/bo4e.bo.html

grafik

Die Highlights sind u.A.:

Vollautomatisierte Diagrammerstellung, d.h. kein manueller Abgleich von Code/Doku und Diagrammen => Weniger Fehler und keine Inkonsistenzen mehr
Die Diagramme sind farblich konsistent mit den bisherigen Diagrammen
Die Diagramme sind nicht überladen (d.h. es werden nicht zu viele aber auch nicht zu wenige Infos eingeblendet)
Die Diagramme enthalten auch die Kardinalitäten
Die Diagramme enthalten anklickbare Links, die auf die Doku der jeweils verwendeten COMs/anderen BOs verweisen (das ist ein neues Feature, was es so in der alten Doku nicht gab)
Die Diagramme geben Aufschluss über die Serialisierung leerer Listen (also leere Liste [] vs. null; vgl. #274)

Die Diagramme werden aktuell als SVG generiert (z.b. hier), und die Links in den jeweiligen Diagrammen verweisen auf die jeweiligen Abschnitt innerhalb der read-the-docs-Doku. Um das ganze jetzt auf bo4e.de einzubinden, bräuchten wir nochmal eure Hilfe:

[ ] Kommt ihr mit SVG als Bildmaterial auf bo4e.de klar? Es wäre unserer Ansicht nach die richtige Lösung, weil es anders als Bilddateien schnell & durchsuchbar ist. Pixelgrafiken würden wir vermeiden wollen.
[ ] Ist es ok, wenn ihr die Bilder von read-the-docs ladet (also im img-src attribute)? Nach bo4e.de gibt es ja ws. keine CD-Pipeline.
[ ] Falls ihr SVG unterstützt: Gibt es eine generische Regel, wie die URL zur jeweils aktuellsten Version eines BO/COM/ENUMs aussieht? Wir bräuchten diese Regel um die Links so zu generieren, dass sie auf bo4e.de verweisen (denn momentan zeigen die links auf read-the-docs)

snsttr commented 2 years ago

Danke euch für die gute Arbeit!

Wäre es vielleicht noch möglich die Verweise auf die ENUMs in den Diagrammen mit aufzunehmen? Der Rest passt für mich!

Bzgl. der Webseite können wir noch einfacher verfahren und von bo4e.de lediglich auf das Github Repo und die Readthedocs Doku verlinken. Die zusätzliche Pflege der ganzen BOs auf bo4e.de ist nämlich recht aufwändig und es kann leicht zu Unstimmigkeiten kommen.

Aus meiner Sicht sollten wir einen Stichtag festlegen, zu dem wir die alte Doku abschalten und einfach auf die neue verweisen. Dafür muss lediglich sichergestellt werden, dass der Stand hier im Repo auch dem aktuellen Stand auf bo4e.de entspricht. Wir haben in den letzten Wochen nämlich ein paar Änderungen vorgenommen, die wir hier noch nicht nachgezogen haben.

hf-kklein commented 2 years ago

Wäre es vielleicht noch möglich die Verweise auf die ENUMs in den Diagrammen mit aufzunehmen?

ist jetzt da (seit #399 gelöst wurde).

hf-kklein commented 2 years ago

Dafür muss lediglich sichergestellt werden, dass der Stand hier im Repo auch dem aktuellen Stand auf bo4e.de entspricht. Wir haben in den letzten Wochen nämlich ein paar Änderungen vorgenommen, die wir hier noch nicht nachgezogen haben.

Hi Tim, auch das haben wir erledigt (siehe #404 für details). Aus unserer Sicht wären wir bereit die Doku komplett auf read-the-docs umzustellen. Von eurer Seite müsste dann nur jemand die links auf der Seite https://www.bo4e.de/dokumentation manuell einmal alle anfassen, sodass sie auf die entsprechenden Stellen auf read-the-docs verweisen. Da gibt es ja permalinks für so ziemlich alles.

hf-kklein commented 1 year ago

Hi @snsttr, seid ihr hier schon weitergekommen?

bo4e / BO4E-python

Automatisierte UML-Diagramme auf bo4e.de integrieren #398