Include Mermaid diagrams in Doxygen

[azrogers]

Mermaid is a JavaScript-based diagramming tool that would be very useful for us to have in our documentation. It would make it easier to create and maintain flow charts, sequence diagrams, and any other sorts of diagrams and charts we need. Implementing Mermaid in Doxygen is very possible, but not trivial. This repository contains an example of one approach to implementing Mermaid, but it might not be the best. We should investigate our options here and implement a way to generate and include these charts in our documentation.

[kring]

It would be great to have access to at least one icon pack, too: https://mermaid.js.org/config/icons.html

[azrogers]

Did some investigating on this issue:

• If we're generating Mermaid charts dynamically, we can use the code from the repo linked in the issue to include Mermaid charts in our doc comments, by adding these lines to our doc/CMakeLists.txt:

  set(DOXYGEN_ALIASES mermaid{1}="\\htmlonly <div class=\\\"mermaid\\\"> ^^ \\endhtmlonly \\htmlinclude \\\"\\1.mmd\\\" \\htmlonly ^^ </div> \\endhtmlonly")
  set(DOXYGEN_VERBATIM_VARS DOXYGEN_ALIASES)
  set(DOXYGEN_EXAMPLE_PATH "${CMAKE_CURRENT_LIST_DIR}/diagrams")

  • This will let us use a command like \mermaid{async} to include the diagram from doc/diagrams/async.mmd. We can then use HTML_HEADER to include the Mermaid JavaScript file on each Doxygen page to turn the Mermaid code into an actual chart.
  • One of the main questions we have to answer is: where do we get that Mermaid JavaScript file from? We can run a bundler like esbuild from our CMake file to compile it at build time from the NPM dependencies. However, when including icon packs in the build, this produces a 12.4MB JavaScript file that we'd be loading for every page.
  • Instead, we can just grab a copy of the latest mermaid.min.js and latest icon pack .json file and include them in the repo. This would reduce the assets loaded by splitting apart the Mermaid code and the icons pack, to allow the icons to be lazy loaded.
  • We can also just grab both from the CDN. This solution is even easier than including the files in our repo, but it does mean the charts wouldn't display at all when viewing the docs offline.
  • Alternatively, we can generate the charts at build time using mermaid-cli. This would require adding a step to the CMake file that runs through every .mmd file we're using and generates SVGs from them. Then, instead of generating a div for dynamically-loaded Mermaid, we can change the alias code above to instead insert the appropriate SVG for each chart. I'm in favor of this solution as it would mean we don't have to load Mermaid at all in the generated documentation, though there might be headaches in this approach that I haven't discovered yet.

[kring]

Instead, we can just grab a copy of the latest mermaid.min.js and latest icon pack .json file and include them in the repo. This would reduce the assets loaded by splitting apart the Mermaid code and the icons pack, to allow the icons to be lazy loaded.

Do you know of any downside to this? It sounds like a solid option.

My only small concern with generating the charts dynamically is that this could (but hopefully doesn't!) prevent them from working when the docs are loaded from a file URL. For example, if a user generates the docs locally and opens the index.html directly without hosting them with a web server.

[azrogers]

The main downside is that it would be slightly more work (as in, three minutes of work versus two minutes) to keep it updated, as compared to changing the version number in the package.json. Not much of a downside. I believe if we include both the Mermaid JS file and the icons pack JSON file in the built docs, it should work offline.