Any Tool for creating Editable Diagrams in LLVM/Clang-REPL Documentation? (similar to Mermaid inGithub)

LLVM Project
1

Hello All,

This is related to documentation specifically, not to coding.

I am a technical writer, trying to contribute to the Clang-REPL documentation. I created some drafts on GitHub, including some flow diagrams in Mermaid, only to realize that a similar tool is not supported out-of-the box in Sphinx/LLVM docs.

I heard about a Graphviz plugin for Sphinx that can be used with LLVM, but I’m uncertain if it is readily available in LLVM documentation site.

What is the best way to add editable diagrams (flowcharts, etc.) to LLVM/Clang/Clang-REPL documentation?

I am new to LLVM (but not to Technical Writing). Any help here would be highly appreciated.

1 Like
2

The existing convention is just to convert diagrams to an image (svg or png). Granted, this has the obvious downside that it’s hard to update, but there’s some benefits: it doesn’t require any in-tree tooling, the rendering is completely predictable, and people can use their preferred tools.

The bot that generates the site should have a standard Linux install of both Sphinx and Graphviz; if that’s enough, it probably works? Probably worth writing a test commit before you do too much work in this direction.

1 Like
3

@efriedma-quic Thanks for the insights :smiling_face:

Yeah I suspected it may be supported, but just wanted to check if someone had tried it before. I have added .png files for now, but will hopefully try out a test commit with a Graphviz diagram as well, as you suggested.

4

Hi @efriedma-quic and all,
We tried the test commit for using graphviz (diagrams convention) in sphinx documentation which can be seen here ⚙ D156858 Add Documentation for Execution Results Handling in Clang-REPL.
I think we need to install graphviz as dependency like recommonmark on our builders as we are getting this error log:Buildbot.
Please let us know whether we are on the right track to achieve the support for graphviz diagrams.

5

Oh, I was assuming it would have graphviz because doxygen uses graphviz to generate graphs… but I guess the doxygen actually runs on a different bot.

CC @gribozavr , who I think maintains the bot in question.

I guess if we’re going to add a dependency on graphviz, we should consider adding some code to CMake to produce a better error message if graphviz isn’t present.