Add Mermaid diagram generators

[bkryza]

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

[DeveloperPaul123]

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

[bkryza]

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~

with only class A<T>...

[DeveloperPaul123]

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

[DeveloperPaul123]

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. https://github.com/mermaid-js/mermaid/issues/4227

[DeveloperPaul123]

@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]

@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]

@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]

@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]

@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]

@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]

@bkryza Awesome, thanks for adding that!

[mahatt]

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]

@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]

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

See https://github.com/mermaid-js/mermaid/issues/3287#event-10265432344 and https://github.com/mermaid-js/mermaid/issues/4565

[bkryza]

@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<T>"] {
    }
    class A002["A<int>"] {
    }
    class A003["A<std::function(int,std::string)>"] {
       +std::vector<std::function(int,std::string)> func  
    }
    A001 <|.. A002
    A001 <|.. A003

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

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 < 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]

@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]

@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]

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