Diagrams as code in Sphinx documentation

[fabcor-maxiv]

It could be nice to be able to have diagrams as code in the documentation. The source code for the diagram itself would be stored as text/code inside the Markdown or ReStructuredText document within a directive.

Possible technical solutions:

• https://mermaid.js.org/
  • https://pypi.org/project/sphinxcontrib-mermaid/
  • https://pypi.org/project/sphinx-mermaid/
• https://plantuml.com/
  • https://pypi.org/project/sphinx-plantuml/
  • https://pypi.org/project/sphinxcontrib-plantuml/
• https://d2lang.com/

[fabcor-maxiv]

See the discussion that initiated this: https://github.com/mxcube/mxcubecore/pull/889#discussion_r1533949138

[fabcor-maxiv]

I guess we should avoid Mermaid-based solutions for now. Mermaid is a Node.js tool, and mxcubecore has no dependency on Node.js. Same for D2, which is a Golang tool.

[marcus-oscarsson]

Very nice :). Mermaid seems a bit more capable than the other two. I had a look at PlantUML and that also looked pretty good so I would be happy with that.

[fabcor-maxiv]

Mermaid seems a bit more capable than the other two.

If there is a preference for Mermaid, we can go with that. The Node.js dependency might not be that big of an issue, I do not know.

I had in mind that both Mermaid and PlantUML were using very similar notation -- implying that it would be easy-ish to switch from one to the other later on if needed -- but that does not seem to be the case after all now that I am looking at those a bit closer.

[fabcor-maxiv]

Turns out there is no need for Node.js for Mermaid after all. At least not for HTML where the transformation from Mermaid code is made directly in the browser. So here is an attempt: https://github.com/mxcube/mxcubecore/pull/954