This extension allows you to embed Mermaid graphs in your documents, including general flowcharts, sequence and gantt diagrams.
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.
.. 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!
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 hierarchie 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.util.SphinxParallelError sphinx.util.ExtensionError :full:
.. autoclasstree:: sphinx.util.SphinxParallelError sphinx.util.ExtensionError :full:
Or directly the module:
.. autoclasstree:: sphinx.util
.. autoclasstree:: sphinx.util
Installation
You can install it using pip
pip install sphinxcontrib-mermaid
Then add sphinxcontrib.mermaid
in extensions
list of your projec't 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.
Config values
mermaid_output_format
The output format for Mermaid when building HTML files. This must be either'raw'
'png'
or'svg'
; the default is'raw'
.mermaid-cli
is required if it's notraw
mermaid_version
The version of mermaid that will be used to parse raw
output in HTML files. This should match a version available on https://unpkg.com/browse/mermaid/. Currently, the default version is 8.4.8.
mermaid_cmd
The command name with which to invokemermaid-cli
program. The default is'mmdc'
; you may need to set this to a full path if it's not in the executable search path.
mermaid_params
For individual parameters, a list of parameters can be added. Refer to https://github.com/mermaidjs/mermaid.cli#options. Examples:
mermaid_params = ['--theme', 'forest', '--width', '600', '--backgroundColor', 'transparent']This will render the mermaid diagram with theme forest, 600px width and transparent background.
mermaid_sequence_config
Allows overriding the sequence diagram configuration. It could be useful to increase the width between actors. It needs to be a json file Check options in the documentation
mermaid_verbose
Use the verbose mode when call mermaid-cli, and show its output in the building process.
mermaid_pdfcrop
If using latex output, it might be useful to crop the pdf just to the needed space. For this, pdfcrop
can be used.
State binary name to use this extra function.
Acknowledge
Much of the code is based on sphinx.ext.graphviz. Thanks to its authors and other Sphinx contributors for such amazing tool.