feat: draw_metamodel in docs #336
Conversation
This comment was marked as off-topic.
This comment was marked as off-topic.
AlexanderLanin
force-pushed
the
meta_draw
branch
from
bd02f89 to
ad9d149
Compare
|
The created documentation from the pull request is available at: docu-html |
|
|
||
| {{draw_metamodel( | ||
| [ | ||
| "feat_arc_sta", "feat", "logic_arc_int", "logic_arc_int_op", "comp_arc_sta", "comp", "real_arc_int", "real_arc_int_op", |
There was a problem hiding this comment.
Is the output alphabetical ordered ? I would like to have it in the original given order or at least by option sorted. The reason is to create an blocks according to the given requirement. Is there any possibility to add artificial line breaks?
There was a problem hiding this comment.
The output is currently alphabetical... thought error. We can use the user provided order.
But arranging images by providing the arguments here in a specific order... that sounds like a suicide risk.
| [ | ||
| "feat_req", | ||
| "comp_req", | ||
| "feat_arc_sta", |
There was a problem hiding this comment.
If this is rendered here, and it shows missing feat_arc_sta is not implemented yet as not drawn, then it already helps for verification here
There was a problem hiding this comment.
Exactly. We could also add some error reporting... but I'm afraid that we would reimplement the metamodel in the draw functions / make them overly strict in what exactly they can actually draw.
|
|
||
| .. needuml:: | ||
|
|
||
| {{draw_metamodel( |
There was a problem hiding this comment.
The picture shows only 6 of 8 components. The interfaces are missing. I would like to show them, also if there are no links available.
There was a problem hiding this comment.
In my examples I've added only the stuff that was mentioned in exactly that requirement. But that's one of the main questions: how do use this draw_metamodel feature in a way that actually helps us.
Signed-off-by: RolandJentschETAS <[email protected]>
Signed-off-by: RolandJentschETAS <[email protected]>
| ) | ||
|
|
||
|
|
||
| class DrawMetamodel: |
There was a problem hiding this comment.
Clever idea. I like it.
Still, I do wonder about our overall approach: Process experts draw diagrams to write requirements which the docs-as-code team turns into a metamodel YAML which gets converted to diagrams again.
There was a problem hiding this comment.
Yeah I was looking through the existing draw functions, and it's a horrible mess. Mixing data collection and plantuml logic all in every line of code. So I made the split of collection -> model -> draw. That makes it more readable and 2/3 reusable. Of course model and draw are super trivial, as that could totally explode if we made it truly generic.
Overall approach: that's kind of my main question here. How to use it reasonably.
I'm sure it can help with reviews / consistency, considering the long line of manual transformations that you've mentioned.
| * all architecture elements defined in :need:`tool_req__docs_arch_types`. | ||
| * all safety analysis elements defined in :need:`tool_req__docs_saf_types`. | ||
|
|
||
| .. admonition:: How is it currently implemented in the current docs-as-code metamodel.yml? |
There was a problem hiding this comment.
Pulling in parts of the implementation into a requirement is weird from a process point of view. It implies testing is not necessary because the requirement implicitly always reflects what is implemented.
Alternatively, we don't consider metamodel.yaml as implementation but as a requirements artifact. In that case, it should not be placed deep within the code.
There was a problem hiding this comment.
Yeah, metamodel could be the requirement. Maybe.
Maybe we need to drop tool requirements.
Maybe we copy process requirements as tool requirements.
etc
There was a problem hiding this comment.
source code link is actually exactly the same. It shows implementation "in" the requirement.
4 participants
As a basis for discussion here is the ability to render the metamodel itself within docs.
Added some exemplary diagrams to https://eclipse-score.github.io/docs-as-code/pr-336/internals/requirements/requirements.html
Not sure yet if/how to use this best. The original idea was to support consistency between process-requirements / tool-requirements and implementation (metamodel.yml). Note that this can be used in needs and in normal text (e.g. concepts), and from any repository.
@a-zw @MaximilianSoerenPollak @RolandJentschETAS @masc2023