search

DSD-DBS / py-capellambse

A Python 3 headless implementation of the Capella modeling tool.
https://dsd-dbs.github.io/py-capellambse/
Apache License 2.0
52 stars 9 forks source link

Document diagraming engine API #25

Open vik378 opened 2 years ago

vik378 commented 2 years ago

To enable further development of diagraming engine we should provide an overview page (documentation) that explains:

ewuerger commented 2 years ago

I assigned @Wuestengecko, @jamilraichouni and myself to this since @Wuestengecko is initially responsible for .aird-parsing, @jamilraichouni recently implemented the diagram-cache sideloading and I created and maintained the svg submodule. That's why I'm convinced that the individual behaviour of these submodules is documented at its best from the respective dev. I think that the .aird-parsing module will take much more work in comparison to the other modules. Therefore and because I'm atleast proficient in the JSON-encoding procedure and the box/edge-factories, I can assist in documenting these parts. For the black magic happening on edge-snapping and routing(localization of bendpoints and anchor points of edges) I'm really curious about its explanation.

Documentation for diagram-rendering subsystem

Individual module documentation

Broad interplay-overview of these modules

[...] The base idea was that the parsing "understands" the diagram-elements and encodes them in base-elements(Box, Edge, Circle,...). From these a json-encoder converts a aird.Diagram to JSON such that the svg module can sequentially draw these objects onto the created canvas [...]. High-level explanation of the interplay shouldn't be hard and I'd say we should do this together(@vik378).

🚀🚀🚀 Opportunity for enhancement 🚀🚀🚀

In documenting these critical modules we should not only celebrate what was done greatly, we'll hopefully see what is implemented suboptimally in order to optimize. One of these "suboptimal" things is the appearance of calculations in the parser, needed to make the location of diagram-elements come as close as possible to the locations shown in capella and another appearance of calculations in the svg module to place decorations and most-importantly text where it belongs, doesn't overflow or overlap and wraps/breaks like displayed in capella. The usage of extent_func, i.e. our font-measurement function, is kind of inflated.

I want to re-emphasize our plans on merging calculations for the diagram-rendering in its own module. Hopefully this can eliminate some of the problems for svg-rendering like for e.g. the standard("untouched") text-box size is fine for displaying text/labels in Sirius-Editor in full but in the rendered export this text is clipped(+ "..." at the end).

\discuss