Mermaid diagrams in yours Sphinx powered docs
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!
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.
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 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.
.. autoclasstree:: sphinx.util sphinx
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' ]
: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.
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
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.
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.
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.
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
Use the verbose mode when call mermaid-cli, and show its output in the building process.
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.
Much of the code is based on sphinx.ext.graphviz. Thanks to its authors and other Sphinx contributors for such amazing tool.
- (nothing yet)
0.4.0 (April 9, 2020)
- Added mermaid_params
- Added config file option
- Improved latex integration
- Added the pdfcrop functionality
- Mermaid version is configurable
- Several cleanups in the code
0.3.1 (Nov 22, 2017)
- Support the new Mermaid CLI by Bastian Luettig
0.3 (Oct 4, 2017)
- several improves and bugfixes contributed by Alberto Berti
0.2.1 (Jun 4, 2017)
- Workaround for opacity issue with rtd’s theme (thanks to Anton Koldaev)
0.2 (Jun 4, 2017)
0.1.1 (Jun 4, 2017)
- Better usage instructions
0.1 (Jul 18, 2016)
- first public version
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
|Filename, size||File type||Python version||Upload date||Hashes|
|Filename, size sphinxcontrib_mermaid-0.4.0-py2.py3-none-any.whl (10.0 kB)||File type Wheel||Python version py2.py3||Upload date||Hashes View|
|Filename, size sphinxcontrib-mermaid-0.4.0.tar.gz (9.6 kB)||File type Source||Python version None||Upload date||Hashes View|
Hashes for sphinxcontrib_mermaid-0.4.0-py2.py3-none-any.whl
Hashes for sphinxcontrib-mermaid-0.4.0.tar.gz