Feature Request: standard mermaid support

[dviererbe]

I recently wanted to use mermaid in the Ubuntu-Packaging-Guide. There already exists a sphinx extension (see: https://pypi.org/project/sphinxcontrib-mermaid/)

Even though it works mostly well, it does not play nice with changing the theme, because the diagrams are either rendered in a light or dark theme all the time and do not change with the remaining website.

I think the Ubuntu Pro documentation is also using mermaid. Therefore instead of every downstream doing it's own implementation to handle this, I would like to support mermaid out of the box and disable it by default.

[s-makin]

+1 from me to this - if we could get some guidance from the web team as well on the styling so that every team using Mermaid also has consistent visual appearance, that would be nice!

[pmatulis]

@s-makin can you cite a page in Ubuntu Pro that uses Mermaid so we have something to model future work on?

[dviererbe]

can you cite a page in Ubuntu Pro that uses Mermaid so we have something to model future work on?

Ubuntu Pro

It is currently a non-public repo, but you should see all mermaid usages through this search:
https://github.com/search?q=repo%3Acanonical%2Fubuntu-pro-docs%20mermaid&type=code

Ubuntu Packaging Guide

• This diagram (and similar) will soon published there:
  Loading

    %%{init: { 'gitGraph': {'mainBranchName': 'debian', 'showCommitLabel': false }} }%%
  gitGraph LR:
     commit tag: "1.2-1"
     branch ubuntu
     commit tag: "1.2-1ubuntu1"
     checkout debian
     commit tag: "1.3-1"
     checkout ubuntu
     merge debian
     commit tag: "1.3-1ubuntu1"
  

  as plain text:

    %%{init: { 'gitGraph': {'mainBranchName': 'debian', 'showCommitLabel': false }} }%%
  gitGraph LR:
     commit tag: "1.2-1"
     branch ubuntu
     commit tag: "1.2-1ubuntu1"
     checkout debian
     commit tag: "1.3-1"
     checkout ubuntu
     merge debian
     commit tag: "1.3-1ubuntu1"
  
• I also plan to adopt this https://github.com/canonical/ubuntu-maintainers-handbook/blob/main/Reference/PathToUploadRights.md

[evilnick]

I think it would make more sense to implement Kroki, which supports a whole range of different diagrams-as-text including PlantUML, mermaid etc. We use it in the Kubernetes docs for Structurizr C4 diagrams

[evilnick]

N.B. This is also supported by a sphinx extension.

[dviererbe]

I think it would make more sense to implement Kroki, which supports a whole range of different diagrams-as-text including PlantUML, mermaid etc. We use it in the Kubernetes docs for Structurizr C4 diagrams

note: +1

question(non-blocking): @evilnick Does the Kroki extension let you zoom in and out of diagrams? The mermaid extension does (see :zoom: in the directive-options section).

issue(non-blocking): Unfortunately the sphinx extension seems not to be already packaged on Ubuntu/Debian 😢 (see https://launchpad.net/ubuntu/+search?text=kroki) which makes packaging harder. See the reasoning in #140 why this may be important. But I can live with that.

[s-makin]

@s-makin can you cite a page in Ubuntu Pro that uses Mermaid so we have something to model future work on?

In the Pro Client docs I can give an additional example to the one that @dviererbe linked from the Pro handbook

https://canonical-ubuntu-pro-client.readthedocs-hosted.com/en/latest/explanations/cves_and_usns_explained/

I'm not familiar with Kroki, but Mermaid seems to be generally quite well regarded because of their accessibility practices. Also, it has a convenient online building tool so you can generate the code for a diagram without needing to know the syntax, which is convenient for those new to code graphics. If Kroki has something similar, I'd give it a +1 too.

[evilnick]

I'm not sure about the zoom support - does that require embedding some javascript also? Kroki is like Diagrams as a Service - it's basically a server you send code to and it sends an image back. It is running actual Mermaid (and Vega and PlantUML and Graphviz) so you don't have to, so theoretically at least, it should support anything that those systems do. Of course, in this case we are relying on the extension to send and receive that info, so that's the bit that may require testing. Normally in sphinx / kroki the options are supported in the same way.

[dviererbe]

it's basically a server you send code to and it sends an image back

issue(blocking): If there is no possibility to run this offline, than this is a deal breaker for the Ubuntu Packaging Guide. We do not have internet access during the build process to guarantee building from source.

note: Additionally I am not a big fan of depending on an external service.

thought: With that said, I have no problem if we add kroki and mermaid. Then every Downstream can choose for themself.

[evilnick]

@dviererbe yes, I had similar concerns, however, kroki also exists as a self-hosted container image, which is what I imagine we would use if it were to be adopted more widely.
I also have no problem with mermaid and Kroki. I think there are some diagram types which are simply done better in plantuml, or simply not covered by mermaid. It would be nice to harmonise some sort of theming too.

[ru-fu]

I agree that we should have a tool for "code diagrams" in the starter pack, with predefined colour schemes.

No opinion from me on which tool is best, since I haven't used any of them enough to be able to judge.
I wouldn't want to include several though - maaaaaybe if they serve very different purposes and we can give clear guidelines on when to use which, but not as a "choose the one you like" option.
The starter pack is supposed to give you a working solution. If you don't agree with the choice of tools, you can customise it to use something else, but we should decide what we want to recommend.

Afaik @tmihoc has done some research on tools and might have some input?

[tmihoc]

Mermaid is probably a good choice.

I've been playing with structurizr, because it supports the c4 model for visualizing software architecture natively, but structurizr allows you to export to Mermaid.