[Doc] Enable Mermaid diagrams in our documentation (#6450)

* Add sphinxcontribute-mermaid extension

* Add manual link for mermaid.js

* Load mermaid.js before require.js to avoid errors

* Update documentation guide for the usage of mermaid diagram in our doc

* Resolve error caused by double loaded mermaid.js

* Small fixes

* Small fix based on comments

docs/readthedocs/requirements-doc.txt

@@ -40,4 +40,5 @@ nbsphinx==0.8.9
 ipython==7.34.0
 sphinx-design==0.2.0
 nbsphinx-link==1.3.0
-pydata-sphinx-theme==0.11.0
+pydata-sphinx-theme==0.11.0
+sphinxcontrib-mermaid==0.7.1

docs/readthedocs/source/_templates/layout.html

@@ -0,0 +1,6 @@
+{% extends "!layout.html" %}
+
+{% block scripts %}
+<script src="https://cdnjs.cloudflare.com/ajax/libs/mermaid/9.2.0/mermaid.min.js" integrity="sha512-bAUSYGDF/K+6ME3orRcyGh86wxE7kBRunb1tPd4btqx+iZrS3CWaxil1KNUNsVw2OlqQJvXw3id+jsPflaK49g==" crossorigin="anonymous" referrerpolicy="no-referrer"></script>
+{{ super() }}
+{% endblock %}

docs/readthedocs/source/conf.py

@@ -113,7 +113,8 @@ extensions = [
     'sphinx_design',
     'nbsphinx',
     'nbsphinx_link',
-    'sphinx.ext.graphviz' # for embedded graphviz diagram
+    'sphinx.ext.graphviz', # for embedded graphviz diagram
+    'sphinxcontrib.mermaid' # for Mermaid diagram
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -159,7 +160,7 @@ exclude_patterns = ['_build']
 html_static_path = ['_static']
 # add js/css for customizing each page
 html_js_files = [
-    'js/custom.js',
+    'js/custom.js'
 ]
 html_css_files = [
     'css/custom.css',
@@ -277,4 +278,7 @@ def setup(app):
 nbsphinx_execute = 'never'
 
 # make output of graphviz diagram to svg
-graphviz_output_format = 'svg'
+graphviz_output_format = 'svg'
+
+# disable automatically included mermaid.js from sphinxcontrib-mermaid to load it before require.js
+mermaid_version=""

docs/readthedocs/source/doc/UserGuide/documentation.md

@@ -445,17 +445,67 @@ You could refer [here](https://sphinx-design.readthedocs.io/en/furo-theme/cards.
 
 Note that `1 2 2 2` defines the number of cards per row in different screen sizes (from extra-small to large).
 
+</td></tr>
+<tr><td>
+
+[Mermaid](https://mermaid-js.github.io/) digrams
+
+</td><td>
+
+```rst
+.. mermaid::
+   
+   flowchart LR
+      A(Node A)
+      B([Node B])
+
+      A -- points to --> B
+      A --> C{{Node C}}
+
+      classDef blue color:#0171c3;
+      class B,C blue;
+```
+
+</td>
+<td>
+
+```eval_rst
+.. mermaid::
+   
+   flowchart LR
+      A(Node A)
+      B([Node B])
+
+      A -- points to --> B
+      A --> C{{Node C}}
+
+      classDef blue color:#0171c3;
+      class B,C blue;
+```
+
+Mermaid is a charting tool for dynamically creating/modifying diagrams. Refer [here](https://mermaid-js.github.io/) for more Mermaid syntax.
+
 </td></tr>
 </table>
 
 ### 3.1 Use reStructuredText in `.md` files
-You could embed reStructuredText into `.md` files through putting reStructuredText code into `eval_rst` code block:
+You could embed reStructuredText into `.md` files through putting reStructuredText code into `eval_rst` code block. It is really useful when you want to use components such as sepcial boxes, tabs, cards, Mermaid diagrams, etc. in your `.md` file.
 ~~~md
 ```eval_rst
 any contents in reStructuredText syntax
 ```
+
+```eval_rst
+.. note::
+   
+   This is a note box.
+
+.. mermaid::
+   
+   flowchart LR
+      A --> B
+```
 ~~~
-It could be useful if you want to use special boxes (e.g. note box) or tabs in your `.md` files.
 
 ```eval_rst
 .. important::