Add handling of Mermaid diagrams in documentation

GitHub: fix mxcube#908

docs/conf.py

@@ -102,6 +102,12 @@
 myst_enable_extensions = ("fieldlist",)
 
 
+# -- Options for sphinxcontrib.mermaid
+# https://pypi.org/project/sphinxcontrib-mermaid/
+
+extensions.append("sphinxcontrib.mermaid")
+
+
 # -- Options for sphinx_last_updated_by_git
 # https://pypi.org/project/sphinx-last-updated-by-git/
 

docs/source/dev/docs.md

@@ -57,6 +57,8 @@ sphinx-build -M html docs/source docs/build -c docs
 
 The theme used is [*furo*](https://pypi.org/project/furo/).
 
+### Markup
+
 The default markup language for Sphinx is
 [*reStructuredText*](https://docutils.sourceforge.io/rst.html).
 The [usage of *Markdown*](https://www.sphinx-doc.org/en/master/usage/markdown.html)
@@ -68,6 +70,8 @@ To learn how to use these features in Markdown documents,
 one should refer to the MyST documentation.
 The docstrings in Python code are still to be written with Restructuredtext syntax, though.
 
+### Python code
+
 The documentation system is configured to generate {doc}`API documentation </dev/api>`
 based on the Python code.
 The Sphinx extension used to do this is
@@ -79,3 +83,41 @@ The
 extension is enabled to handle docstrings within the Python code
 and it is configured for
 [Google-style docstrings](https://google.github.io/styleguide/pyguide.html#s3.8-comments-and-docstrings).
+
+### Diagrams
+
+The
+[*`sphinxcontrib-mermaid`*](https://pypi.org/project/sphinxcontrib-mermaid)
+extension is enabled to allow embedding [*Mermaid* diagrams](https://mermaid.js.org/)
+in the documentation.
+
+For example the following code in a Markdown document:
+
+~~~markdown
+```{mermaid}
+sequenceDiagram
+participant Alice
+participant Bob
+Alice->John: Hello John, how are you?
+```
+~~~
+
+or the following in a ReStructuredText document:
+
+```restructuredtext
+.. mermaid::
+
+    sequenceDiagram
+    participant Alice
+    participant Bob
+    Alice->John: Hello John, how are you?
+```
+
+produce the following diagram:
+
+```{mermaid}
+sequenceDiagram
+participant Alice
+participant Bob
+Alice->John: Hello John, how are you?
+```

pyproject.toml

@@ -62,6 +62,7 @@ furo = "^2023.9.10"
 myst-parser = "^2.0.0"
 sphinx = "<7.2"
 sphinx-last-updated-by-git = "^0.3.7"
+sphinxcontrib-mermaid = "^0.9.2"
 
 [tool.poetry.extras]
 tango = ["PyTango"]