diff --git a/docs/readthedocs/requirements-doc.txt b/docs/readthedocs/requirements-doc.txt index fc99b162..8dbd8e27 100644 --- a/docs/readthedocs/requirements-doc.txt +++ b/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 \ No newline at end of file +pydata-sphinx-theme==0.11.0 +sphinxcontrib-mermaid==0.7.1 \ No newline at end of file diff --git a/docs/readthedocs/source/_templates/layout.html b/docs/readthedocs/source/_templates/layout.html new file mode 100644 index 00000000..a5acfd3c --- /dev/null +++ b/docs/readthedocs/source/_templates/layout.html @@ -0,0 +1,6 @@ +{% extends "!layout.html" %} + +{% block scripts %} + +{{ super() }} +{% endblock %} diff --git a/docs/readthedocs/source/conf.py b/docs/readthedocs/source/conf.py index b274fbac..c938525c 100644 --- a/docs/readthedocs/source/conf.py +++ b/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' \ No newline at end of file +graphviz_output_format = 'svg' + +# disable automatically included mermaid.js from sphinxcontrib-mermaid to load it before require.js +mermaid_version="" diff --git a/docs/readthedocs/source/doc/UserGuide/documentation.md b/docs/readthedocs/source/doc/UserGuide/documentation.md index 7ef0a12a..ec151088 100644 --- a/docs/readthedocs/source/doc/UserGuide/documentation.md +++ b/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). + + + +[Mermaid](https://mermaid-js.github.io/) digrams + + + +```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; +``` + + + + +```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. + ### 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::