Stream: docs

Topic: switch from dot/graphviz to mermaid

view this post on Zulip Philip Durbin 🚀 (May 28 2026 at 19:36):

@Ash Manda has figured out how to switch from dot/graphviz to mermaid: https://github.com/IQSS/dataverse/compare/develop...srmanda-cs:dataverse:12408-move-docs-jenkins-builds

view this post on Zulip Philip Durbin 🚀 (May 28 2026 at 19:37):

Should we do it?

view this post on Zulip Philip Durbin 🚀 (May 28 2026 at 19:39):

It looks like we can pip install https://pypi.org/project/sphinxcontrib-mermaid/

view this post on Zulip Oliver Bertuch (May 28 2026 at 19:40):

I'm not opposed to it (gives us more options for graphs), but here are some thoughts.

  1. We will require adding an external Javascript unless we provide it ourselves.
  2. While I do appreciate having more options to render graphs, our custom CSS might get in the way. I've had more than run in with our custom style and formatting things like code blocks. This needs testing.

view this post on Zulip Philip Durbin 🚀 (May 28 2026 at 19:41):

Good points. One thing I'll say is that removing the need to install graphviz will simplify everything. I've seen people stumble on this.

view this post on Zulip Oliver Bertuch (May 28 2026 at 19:42):

Using a Javascript wrapper like Mermaid might give them trouble, too. Browsers are picky when it comes to loading Javascript when you access the built HTML pages via files:///.

view this post on Zulip Oliver Bertuch (May 28 2026 at 19:42):

If you're like me, always using sphinx-autobuild, this won't be a problem at all.

view this post on Zulip Ash Manda (May 28 2026 at 19:43):

My two cents when it comes to hosting the docs specifically:

  1. Maintenance burden reduces. With Graphviz you always need access to a CI pipeline or a full server runner just to render the documentation
  2. DOT language is not human friendly whatsoever. Mermaid reads like English, very easy for contributors to get started with
  3. Mermaid renders natively on GitHub, DOT won't. Contributors can easily preview changes
  4. Graphviz is a lot more powerful when it comes to layout, but Mermaid has a more active ecosystem since GitLab, Notion, etc etc everything supports mermaid by default

view this post on Zulip Philip Durbin 🚀 (May 28 2026 at 19:44):

I do love Mermaid. I get a nice preview in VS Code.

view this post on Zulip Oliver Bertuch (May 28 2026 at 19:44):

@Ash Manda you might not be aware, but we will always need to run a Sphinx build anyway. It's not enough to just drop the RST (or MD) files someplace. Does any other static site hoster aside from ReadTheDocs do that for us?

view this post on Zulip Ash Manda (May 28 2026 at 19:46):

Well, like you said I obviously don't have the full context of how this change will affect people.

But from my perspective. For a GitHub pages hosting, you need two YAML files that require on-going maintenance.

On Cloudflare, this is all I pasted into the deployment: cd doc/sphinx-guides && pip install -r requirements.txt && make html && make epub && cp build/epub/Dataverse.epub build/html and it just worked, and it auto-updates both master and develop without me touching it.

view this post on Zulip Ash Manda (May 28 2026 at 19:48):

I couldn't do that with graphviz because a lot of these serverless environment don't support installation of dot for the build step.

view this post on Zulip Oliver Bertuch (May 28 2026 at 19:53):

Again, I'm not saying we shouldn't go for Mermaid. Just raising the point of let's not force people to download Javascript from a different server and the generated graphs need to be checked for compatibility with the bootstrap based Sphinx CSS

view this post on Zulip Ash Manda (May 28 2026 at 19:54):

Absolutely! Just giving my two cents from where I'm standing. The final decision is always the teams'. Just here to offer perspectives

view this post on Zulip Philip Durbin 🚀 (May 28 2026 at 19:55):

Said another way, you like that https://guides.dataverse.org/en/6.10.1/_images/graphviz-e1d7238a02d1da6a8a101ce4c3238e0edc4eb546.png is a PNG, right, @Oliver Bertuch? No CSS to deal with. The final output is a PNG.

view this post on Zulip Oliver Bertuch (May 28 2026 at 19:56):

The mermaid extension may use some wrapping HTML code that is not 100% compatible with our CSS. No matter if it's rendered as SVG or PNG.

view this post on Zulip Philip Durbin 🚀 (May 28 2026 at 19:56):

right, right

view this post on Zulip Oliver Bertuch (May 28 2026 at 19:56):

For example when using a filename on a codeblock, the CSS all of a sudden makes it full width. :shrugdog:

view this post on Zulip Oliver Bertuch (May 28 2026 at 19:57):

This completely brakes the layout of the page...

view this post on Zulip Philip Durbin 🚀 (May 28 2026 at 19:57):

edge cases, right

view this post on Zulip Philip Durbin 🚀 (May 28 2026 at 20:15):

Does Mermaid work when building a PDF? dot/graphviz works fine:

Screenshot 2026-05-28 at 4.14.33 PM.png

From "PDF (experimental!)" at https://dataverse-smr.pages.dev/versions#guides-versions

view this post on Zulip Ash Manda (May 28 2026 at 20:18):

I do not believe it can. At least not natively like graphviz

view this post on Zulip Philip Durbin 🚀 (May 28 2026 at 20:26):

Hmm. So maybe we should keep graphviz.

view this post on Zulip Philip Durbin 🚀 (May 28 2026 at 20:27):

We could switch graphviz to the PlantUML model. With that tool we encourage doc writers to build the images locally and commit them (and the source) into the repo.

view this post on Zulip Philip Durbin 🚀 (May 28 2026 at 20:28):

https://guides.dataverse.org/en/6.10.1/_images/3webservers.png comes from https://github.com/IQSS/dataverse/blob/v6.10.1/doc/Architecture/components.uml for example.

view this post on Zulip Oliver Bertuch (May 28 2026 at 20:29):

Also we really should avoid doing that as well - it would be good to just use a proper build chain for it and use sphinx contrib plantuml.

view this post on Zulip Oliver Bertuch (May 28 2026 at 20:29):

Also, whatever we do with Mermaid is also possible with PlantUML (with whatever it supports), but suffers from the same potential problems.

view this post on Zulip Philip Durbin 🚀 (May 28 2026 at 20:30):

yeah, you're probably right

view this post on Zulip Oliver Bertuch (May 28 2026 at 20:31):

Looking at https://sphinxcontrib-mermaid-demo.readthedocs.io/en/latest/, it says that for non-HTML exports it uses the mermaid-cli tool. This may need installation.

view this post on Zulip Philip Durbin 🚀 (May 28 2026 at 20:31):

huh, ok!

view this post on Zulip Philip Durbin 🚀 (May 28 2026 at 20:32):

I mean, at a high level to we want to get down to one tool, mermaid, instead of the two we have now, dot/graphviz and plantuml?

view this post on Zulip Philip Durbin 🚀 (May 28 2026 at 20:32):

or do we want MORE TOOLS?!?

view this post on Zulip Oliver Bertuch (May 28 2026 at 20:32):

Sounds fine to me. (Single tool)

view this post on Zulip Oliver Bertuch (May 28 2026 at 20:33):

I do admit that I sometimes had trouble with Mermaid when creating larger diagrams using C4. PlantUML felt like more controlable with regards to layout.

view this post on Zulip Oliver Bertuch (May 28 2026 at 20:34):

I should also mention that we could drop graphviz in favor of PlantUML, too.

view this post on Zulip Oliver Bertuch (May 28 2026 at 20:35):

Potentially Mermaid is good enough. :shrugdog:

view this post on Zulip Philip Durbin 🚀 (May 28 2026 at 20:41):

I think I only have one graphviz image, that API Guide one above. The rest are yours, @Oliver Bertuch:

Stuff like that. ^^

view this post on Zulip Philip Durbin 🚀 (May 28 2026 at 20:41):

And I'm fine with moving my one thing to whatever, including PlantUML.

Last updated: May 30 2026 at 06:18 UTC