.. _mermaid_example:

Mermaid Example
~~~~~~~~~~~~~~~

There is a plugin for ``sphinx`` called ``sphinxcontrib-mermaid`` which adds support for embedding ``Mermaid`` graphs
in your documents, including general flowcharts, sequence diagrams, gantt diagrams and more. One can achieve this by following these instructions:

#. Make sure you have the ``sphinx`` plugin for ``mermaid`` (installable via ``pip``)

   .. code-block:: bash

      pip install sphinxcontrib-mermaid

#. Make sure that this plugin would be recognized in your ``conf.py`` by adding it to the ``extentions`` list

   .. note::

      In this project the ``conf.py`` is generated by ``cmake`` from the ``conf.py.in`` file and therefore
      this addition should be added to ``conf.py.in`` since it's the template file for the generated ``conf.py``.


   .. code-block:: python

      extentions = [
          ...
          "sphinxcontrib.mermaid",
          ...
      ]

After those instructions you should be able to add the following directives in your ``.rst`` files

.. code-block:: rst

   .. mermaid::

      sequenceDiagram
         participant Alice
         participant Bob
         Alice->John: Hello John, how are you?
         loop Healthcheck
             John->John: Fight against hypochondria
         end
         Note right of John: Rational thoughts <br/>prevail...
         John-->Alice: Great!
         John->Bob: How about you?
         Bob-->John: Jolly good!

Here is how it looks (this is a very small sequence diagram)

.. mermaid::

   sequenceDiagram
      participant Alice
      participant Bob
      Alice->John: Hello John, how are you?
      loop Healthcheck
          John->John: Fight against hypochondria
      end
      Note right of John: Rational thoughts <br/>prevail...
      John-->Alice: Great!
      John->Bob: How about you?
      Bob-->John: Jolly good!