Open Source Tool to draw diagrams as code

[FaGru3n]

I just want start a disscussion about possibilities to draw diagrams as code with open source tools.

I have already seen some good approches in some of Eclipse Tractus-X repositories.

Do you have already used some kind of tools like PlantUML, Mermaid or something like that?
Do you have an personal favorite that also can be easily used by all working members within Eclipse Tractus X?
Of course these tools have to be aligned with allowed open source licences of the Eclipse Foundation.

So basically can we all align to one (or at least a few) format / tool / option we want to use?
The reason would be to make it easier for everyone to maintain / update diagrams.

[FaGru3n]

Hi all,

cool thing that we already got 13 votes for this poll and it seems that PlantUML will be winning 😉

[FaGru3n]

Hi @eclipse-tractusx/automotive-tractusx-committers,

just a little reminder 😉

found also a cool intro for mermaid:
https://github.blog/2022-02-14-include-diagrams-markdown-files-mermaid/

basically you can write it directly on markdown into github and reference it as code-block :
example:

```mermaid
  graph TD;
      A-->B;
      A-->C;
      B-->D;
      C-->D;
```

will look like:

  graph TD;
      A-->B;
      A-->C;
      B-->D;
      C-->D;

Loading

[evegufy]

Great that you provided this intro!
That it integrates automatically with markdown on GitHub, makes Mermaid very easy to setup and especially convenient for our use case.
Here an example from our team

[matbmoser]

Wow this is awesome! Maybe is really convenient to use this tool. However my question is does it gets complicated when we want to create complex data structures?

[FaGru3n]

for me personally, i have no profounded knowledge about the language, but seems nice to implement and also a live editor online and plugin's for IDE are available

• e.g https://marketplace.visualstudio.com/items?itemName=tomoyukim.vscode-mermaid-editor
• https://plugins.jetbrains.com/plugin/20146-mermaid

more complex example 😉

erDiagram
    CUSTOMER }|..|{ DELIVERY-ADDRESS : has
    CUSTOMER ||--o{ ORDER : places
    CUSTOMER ||--o{ INVOICE : "liable for"
    DELIVERY-ADDRESS ||--o{ ORDER : receives
    INVOICE ||--|{ ORDER : covers
    ORDER ||--|{ ORDER-ITEM : includes
    PRODUCT-CATEGORY ||--|{ PRODUCT : contains
    PRODUCT ||--o{ ORDER-ITEM : "ordered in"

Loading

[Martin-Aulich]

We started using plantUML for the SSI Library, our experience was positive and we added docker based scripts for .puml to .png conversion, so it works locally on windows/linux/mac as well as in the pipeline.
You can see an example in this PR

[gerlitmcoding]

I like mermaid, because it integrates seamless out of the box with GitHub markdown. But we have also to consider more complex diagrams which must be done via draw.io for example.

[Siegfriedk]

Hey, I don’t think you will be able to use draw.io in eclipse tractus-x. While im positive surprised that it is opensource, it’s a hosted application which would be needed to be hosted somewhere so it is accessable. Just imagine you create a diagram and an external contributor wants to fix or extend it, they need to be able to edit it. Tx, Sigi From: gerlitmcoding ***@***.***> Date: Thursday, 15. June 2023 at 13:50 To: eclipse-tractusx/sig-infra ***@***.***> Cc: Kiermayer, Siegfried ***@***.***>, Team mention ***@***.***> Subject: Re: [eclipse-tractusx/sig-infra] Open Source Tool to draw diagrams as code (Discussion #19) I like mermaid, because it integrates seamless out of the box with GitHub markdown. But we have also to consider more complex diagrams which must be done via draw.io for example. — Reply to this email directly, view it on GitHub<#19 (comment)>, or unsubscribe<https://github.com/notifications/unsubscribe-auth/ALLDGX2A5C7F2V4KVMPHJ6TXLLZGPANCNFSM6AAAAAAXS4ZRVQ>. You are receiving this because you are on a team that was mentioned.Message ID: ***@***.***>

[gerlitmcoding]

In general, it is. See here: https://drawio.freshdesk.com/support/solutions/articles/16000042371-embed-a-diagram-in-github-markdown

[Siegfriedk]

Hey, Yes its doable but I’m not sure how ‘stable’ this might be. If draw.io changes its permissions or rules or anything, its gone. We can discuss it or add it to the list and I can ask Daniel Miehle and a person from the Eclipse Foundation about thoughts. I do like draw.io and do see the appeal. Bye, Sigi From: gerlitmcoding ***@***.***> Date: Thursday, 15. June 2023 at 16:17 To: eclipse-tractusx/sig-infra ***@***.***> Cc: Kiermayer, Siegfried ***@***.***>, Team mention ***@***.***> Subject: Re: [eclipse-tractusx/sig-infra] Open Source Tool to draw diagrams as code (Discussion #19) In general, it is. See here: https://drawio.freshdesk.com/support/solutions/articles/16000042371-embed-a-diagram-in-github-markdown — Reply to this email directly, view it on GitHub<#19 (reply in thread)>, or unsubscribe<https://github.com/notifications/unsubscribe-auth/ALLDGX34I6H742LT7PG5FKTXLMKQXANCNFSM6AAAAAAXS4ZRVQ>. You are receiving this because you are on a team that was mentioned.Message ID: ***@***.***>

[gerlitmcoding]

For sure, you are right. But what is and will always be possible is, to store and work in your local branch with a "mydiagram.drawio.svg" file where you can directly modify it in your local draw.io application. But you do not have to convert it. It is by default an SVG which will be updated in your remote github markdown after pushing.

[FaGru3n]

Hi all,

developed a resusable workflow wich generates static files found from your repository.

PUML
https://github.com/eclipse-tractusx/sig-infra#generate-static-plantuml-files
Mermain
https://github.com/eclipse-tractusx/sig-infra#generate-static-mermaid-files

Basically my problem was how to commit and where to commit, whithin your repository so generated only the example how to generate the static files, how you want to store the generated files have to developed by yourself.

But just want to get your feedback an toughts about this 😉

[FaGru3n]

Hi all,

developed a resusable workflow wich generates static files found from your repository.

PUML https://github.com/eclipse-tractusx/sig-infra#generate-static-plantuml-files Mermain https://github.com/eclipse-tractusx/sig-infra#generate-static-mermaid-files

Basically my problem was how to commit and where to commit, whithin your repository so generated only the example how to generate the static files, how you want to store the generated files have to developed by yourself.

But just want to get your feedback an toughts about this 😉

I would suggest the discussion is done here, and can be further discussed in the menitioned PR.

Thanks for your votes and toughts about this.

[ma3u]

Plain UML is a great and easy
tool for activity and sequence diagrams I prefer personally. But we should use the same style and theme: https://plantuml.com/theme

For the overall architecture we are using Archi: https://www.archimatetool.com/

For BPMN we used draw.io.

By now I re-used the existing drawing tool, I found in the GitHub repository. So I try to avoid confusion for that team.

[FaGru3n]

i would suggest you mean, also Plant UML so then which tool you use to generate, should only used with the free and open source perspective and aligend with Eclipse Foundation Licences. If the Tool Archi fits for you is also fine, and as stated in eclipse-tractusx/eclipse-tractusx.github.io#401.
So current purposal TRG fits for .puml and .mermaid... 😉.

[gerlitmcoding]

What are the benefits of using plantuml instead of mermaid? The benifit of using mermaid from my point of view is the build in rendering in md files. You don't need any server behind and no need to generate a static file/picture.

[FaGru3n]

personally i'm on your side.

[mhellmeier]

There are people and teams working with plantuml for several years with no experience on mermaid. Since the syntax of mermaid differs, it isn't always easy or possible to force people to learn a new diagram description language.