NAME¶

sphinxcontrib-mermaid - sphinxcontrib-mermaid documentation

This extension allows you to embed Mermaid graphs in your documents, including general flowcharts, sequence diagrams, gantt diagrams and more.

It adds a directive to embed mermaid markup. For example:

.. 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!

By default, the HTML builder will simply render this as a div tag with class="mermaid", injecting the external javascript, css and initialization code to make mermaid works.

For other builders (or if mermaid_output_format config variable is set differently), the extension will use mermaid-cli to render as to a PNG or SVG image, and then used in the proper code. [graph]

You can also embed external mermaid files, by giving the file name as an argument to the directive and no additional content:

.. mermaid:: path/to/mermaid-gantt-code.mmd

As for all file references in Sphinx, if the filename is not absolute, it is taken as relative to the source directory.

In addition, you can use mermaid to automatically generate a diagram to show the class inheritance using the directive autoclasstree. It accepts one or more fully qualified names to a class or a module. In the case of a module, all the class found will be included.

Of course, these objects need to be importable to make its diagram.

If an optional attribute :full: is given, it will show the complete hierarchy of each class.

The option :namespace: <value> limits to the base classes that belongs to this namespace. Meanwhile, the flag :strict: only process the classes that are strictly defined in the given module (ignoring classes imported from other modules).

For example:

.. autoclasstree:: sphinx.errors.SphinxParallelError sphinx.errors.ExtensionError


   :full:

Or directly the module:

.. autoclasstree:: sphinx.errors

You can install it using pip

pip install sphinxcontrib-mermaid

Then add sphinxcontrib.mermaid in extensions list of your project's conf.py:

extensions = [


    ...,


    'sphinxcontrib.mermaid'
]

DIRECTIVE OPTIONS¶

:alt:: determines the image's alternate text for HTML output. If not given, the alternate text defaults to the mermaid code.

:align:: determines the image's position. Valid options are 'left', 'center', 'right'

:caption:: can be used to give a caption to the diagram.

:zoom:: can be used to enable zooming the diagram. For a global config see mermaid_d3_zoom` below.

CONFIG VALUES¶

mermaid_output_format

mermaid_version

html_js_files = [


   'js/mermaid.js',
]

mermaid_init_js

Changed in version 0.7: The init code doesn't include the <script> tag anymore. It's automatically added at build time.

mermaid_cmd

mermaid_cmd_shell

mermaid_params

mermaid_params = ['--theme', 'forest', '--width', '600', '--backgroundColor', 'transparent']

mermaid_sequence_config

mermaid_verbose

mermaid_pdfcrop

mermaid_d3_zoom

MARKDOWN SUPPORT¶

You can include Mermaid diagrams in your Markdown documents in Sphinx. You just need to setup the markdown support in Sphinx via myst-parser . See a minimal configuration from the tests

Then in your .md documents include a code block as in reStructuredTexts:

```{mermaid}


    sequenceDiagram


      participant Alice


      participant Bob


      Alice->John: Hello John, how are you?
```

BUILDING PDFS ON READTHEDOCS.IO¶

In order to have Mermaid diagrams build properly in PDFs generated on readthedocs.io, you will need a few extra configurations.

build:


  os: ubuntu-20.04


  tools:


    python: "3.8"


    nodejs: "16"


  jobs:


    post_install:


      - npm install -g @mermaid-js/mermaid-cli

# .readthedocs.yaml
# Read the Docs configuration file
# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
# Required
version: 2
# Set the version of Python and other tools you might need
build:


  os: ubuntu-20.04


  tools:


    python: "3.8"


    nodejs: "16"


  jobs:


    post_install:


      - npm install -g @mermaid-js/mermaid-cli
# Build documentation in the docs/ directory with Sphinx
sphinx:


   configuration: docs/conf.py
# If using Sphinx, optionally build your docs in additional formats such as PDF
formats:


  - epub


  - pdf
python:


   install:


   - requirements: docs/requirements.txt

{


  "args": ["--no-sandbox"]
}

mermaid_params = ['-p' 'puppeteer-config.json']

AUTHOR¶

Martín Gaitán

COPYRIGHT¶

2017-2024, Martín Gaitán