Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add Mermaid diagram generators #27

Closed
bkryza opened this issue Mar 21, 2022 · 18 comments · Fixed by #179
Closed

Add Mermaid diagram generators #27

bkryza opened this issue Mar 21, 2022 · 18 comments · Fixed by #179
Labels
enhancement New feature or request
Milestone

Comments

@bkryza
Copy link
Owner

bkryza commented Mar 21, 2022

Add at least basic support for generation of Mermaid (https://mermaid-js.github.io) diagrams in addition to PlantUML...

@bkryza bkryza added the enhancement New feature or request label Mar 21, 2022
@DeveloperPaul123
Copy link

This would be very useful for us to keep diagrams in markdown documentation automatically up to date

@bkryza
Copy link
Owner Author

bkryza commented Jan 26, 2023

This is currently on hold due to too limited template class rendering (called in Mermaid generictype) for instance the following code:

classDiagram

class A~T~ {
    +T value
}

class A~T,N~ {
    
}

class A~int~ {
    
}

A~int~ <|.. A~T~

renders the following diagram:

classDiagram

class A~T~ {
    +T value
}

class A~T,N~ {
    
}

class A~int~ {
    
}

A~int~ <|.. A~T~
Loading

with only class A<T>...

@DeveloperPaul123
Copy link

That's a shame. Seems like there is an open issue for mermaid regarding this mermaid-js/mermaid#3287 ? But no movement sadly.

@DeveloperPaul123
Copy link

Looks like there is some movement on the mermaid issue and there is a Mermaid Chart team that's going to be tackling some issues. mermaid-js/mermaid#4227

@DeveloperPaul123
Copy link

@bkryza Even with the limitation for class templates, would it still be worth pursuing this so that diagrams can be generated for non-template code?

@bkryza
Copy link
Owner Author

bkryza commented Mar 28, 2023

@DeveloperPaul123 Personally to me it's not worth it as this is very serious limitation and the effort related to developing it and even more so on maintaining it is just too big. However, if Mermaid finally supports them then I will definitely reconsider!

Also, if you're really pressed to have diagrams in Mermaid format, please note that clang-uml now has a JSON generator, which basically dumps it's internal diagram model in JSON format (simply add -g json to command line), which should be relatively trivial to convert to any other format using some Python script. Examples of the output are in the test cases, e.g.:

https://github.com/bkryza/clang-uml/blob/master/docs/test_cases/t00002.md#generated-json-models

@DeveloperPaul123
Copy link

@bkryza That seems reasonable; and thanks for the tip regarding JSON output, I missed that part of the docs. We can look into pursuing that.

How stable is the JSON output format at this point?

@bkryza
Copy link
Owner Author

bkryza commented Mar 29, 2023

@DeveloperPaul123 This is a good question :-) On the one hand I'd like to think that at least the overall structure of the JSON is stable, as I already have substantial amount of test cases for it, but on the other hand it is a very new feature so it also depends on the feedback I get on it...

@DeveloperPaul123
Copy link

@bkryza That seems reasonable. In the short term, until feedback is received, would it be possible to add a version parameter to indicate the schema version?

@bkryza
Copy link
Owner Author

bkryza commented Apr 7, 2023

@DeveloperPaul123 The latest version (0.3.4) now contains by default the following JSON element:

  "metadata": {
    "clang_uml_version": "0.3.4",
    "llvm_version": "Ubuntu clang version 15.0.6",
    "schema_version": 1
  },

@DeveloperPaul123
Copy link

@bkryza Awesome, thanks for adding that!

@mahatt
Copy link

mahatt commented Jun 1, 2023

Hi @bkryza , mermaid layout looks quite lot like dot, with dot engine layout. I was trying to convert json to dot and render, had success with less than 15 class nodes. I am curious what are lucrative features from mermaid ?

@bkryza
Copy link
Owner Author

bkryza commented Jun 1, 2023

@mahatt The main benefit of MermaidJS is that the diagrams can be rendered in-browser, so you can just keep their source in your Markdown documentation and the diagrams are generated on the fly, in particular GitHub's markdown supports it.

Unfortunately, due to current very limited support for template parameters/arguments in Mermaid, this issue is on hold - I keep it open for discussions and hopefully if Mermaid's handling of templates is improved I might considering adding support for it...

@DeveloperPaul123
Copy link

It looks like mermaid has potentially fixed issues with template types. They have a PR that has been merged.

See mermaid-js/mermaid#3287 (comment) and mermaid-js/mermaid#4565

@bkryza
Copy link
Owner Author

bkryza commented Sep 4, 2023

@DeveloperPaul123 I've deployed locally their latest develop branch but unfortunately it still doesn't support properly template specializations, however the good news is I found a way (though a bit convoluted) to actually get it to render template specializations:

classDiagram
    class A001["A&lt;T>"] {
    }
    class A002["A&lt;int>"] {
    }
    class A003["A&lt;std::function(int,std::string)>"] {
       +std::vector&lt;std::function(int,std::string&rpar;> func  
    }
    A001 <|.. A002
    A001 <|.. A003
classDiagram
    class A001["A&lt;T>"] {
    }
    class A002["A&lt;int>"] {
    }
    class A003["A&lt;std::function(int,std::string)>"] {
       +std::vector&lt;std::function(int,std::string&rpar;> func  
    }
    A001 <|.. A002
    A001 <|.. A003
Loading

In a nutshell, I can just generate class names based on unique identifiers in my model, and then generate the actual class label and use the unique class names for relationships.
The tricky part here was to figure out to use &lt; for left angle bracket because for some reason otherwise there is a parse error in javascript console in the browser.

The question is whether you care about how the actual diagram source code looks like - or are you just interested in the output diagram?

Anyway with this, I'll definitely revisit the MermaidJS generator, maybe even for the next release...

@DeveloperPaul123
Copy link

@bkryza Thanks for the update!

For me personally I would say that we care more about the generated diagram, and not so much what the diagram source code looks like.

@bkryza bkryza added this to the Release 0.4.0 milestone Sep 6, 2023
@bkryza bkryza mentioned this issue Sep 13, 2023
@bkryza
Copy link
Owner Author

bkryza commented Sep 13, 2023

@DeveloperPaul123 Latest release 0.4.0 now contains support for MermaidJS for all types of diagrams supported already for PlantUML (just add -g mermaid in command line options). I've tried to keep as many of the PlantUML features as possible in the mermaid generator but there are some differences (e.g. missing packages/namespaces option in class diagrams).

You can browse through test cases documentation to compare PlantUML and Mermaid diagrams generates from the same code snippets.

If you'll have any specific issues with Mermaid generator please open new issue...

@DeveloperPaul123
Copy link

@bkryza This is amazing! Thanks for the update. I'll be sure to give this a try on some of our projects. Thanks again

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
enhancement New feature or request
Projects
None yet
Development

Successfully merging a pull request may close this issue.

3 participants