Skip to main content
This is a pre-production deployment of Warehouse. Changes made here affect the production instance of PyPI (pypi.python.org).
Help us improve Python packaging - Donate today!

Mermaid diagrams in yours Sphinx powered docs

Project Description
This extension allows you to embed `Mermaid <http://knsv.github.io/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 <http://knsv.github.io/mermaid/#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 absolute, it is
taken as relative to the source directory.


In addition, you can use mermaid to automatically generate a diagram to show the inheritance of classes
for a given module using the directive ``autoclasstree``. This receive the module, and optionally the relative namespace. Obviously, the module need to be importable to be represented.

For example::


.. autoclasstree:: sphinx.util sphinx


.. autoclasstree:: sphinx.util sphinx


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 not ``raw``

Also note ``'svg'`` support is very experimental in mermaid.


``mermaid_cmd``

The command name with which to invoke ``mermaid-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_phantom_path``

PhantomJS (version ^1.9.0) to be installed and available in your $PATH, or you can specify it's location with in this config variable.


``mermaid_sequence_config``

Allows overriding the sequence diagram configuration. It could be useful to increase the width between actors. It **should be a normal python dictionary**
Check options in the `documentation <https://mermaidjs.github.io/sequenceDiagram.html#configuration>`_

``mermaid_verbose``

Use the verbose mode when call mermaid-cli, and show its output in the building
process.


Acknowledge
-----------

Much of the code is based on `sphinx.ext.graphviz <http://www.sphinx-doc.org/en/stable/ext/graphviz.html>`_. Thanks to its authors and other Sphinx contributors for such amazing tool.


Changelog
---------

0.3.1 (Nov 22, 2017)
+++++++++++++++++++

- Support the new Mermaid CLI by `Bastian Luettig <https://github.com/bastiedotorg>`_


0.3 (Oct 4, 2017)
+++++++++++++++++++

- several improves and bugfixes contributed by `Alberto Berti <https://github.com/azazel75>`_

0.2.1 (Jun 4, 2017)
+++++++++++++++++++

- Workaround for opacity issue with rtd's theme (thanks to `Anton
Koldaev <http://github.com/iroller>`_)

0.2 (Jun 4, 2017)
+++++++++++++++++

- Python 3 support fix (thanks to `Shakeeb
Alireza <http://github.com/shakfu>`_)
- In-browser diagram generation
- Autoclasstree directive. (Thanks to
`Zulko <http://github.com/zulko>`_)

0.1.1 (Jun 4, 2017)
+++++++++++++++++++

- Better usage instructions
- Bugfix

0.1 (Jul 18, 2016)
++++++++++++++++++

- first public version


Release History

Release History

This version
History Node

0.3.1

History Node

0.3

History Node

0.2.1

History Node

0.2

History Node

0.1.1

History Node

0.1

Download Files

Download Files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

File Name & Checksum SHA256 Checksum Help Version File Type Upload Date
sphinxcontrib_mermaid-0.3.1-py2.py3-none-any.whl (11.8 kB) Copy SHA256 Checksum SHA256 py2.py3 Wheel Nov 22, 2017

Supported By

WebFaction WebFaction Technical Writing Elastic Elastic Search Pingdom Pingdom Monitoring Dyn Dyn DNS Sentry Sentry Error Logging CloudAMQP CloudAMQP RabbitMQ Heroku Heroku PaaS Kabu Creative Kabu Creative UX & Design Fastly Fastly CDN DigiCert DigiCert EV Certificate Rackspace Rackspace Cloud Servers DreamHost DreamHost Log Hosting