Mermaid diagrams in yours Sphinx powered docs
Project description
sphinxcontrib-mermaid
=====================
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!
The code will be rendered to a PNG (default) or SVG image (experimental)
(see :confval:`mermaid_output_format`) using `mermaid-cli <http://knsv.github.io/mermaid/#mermaid-cli>`_.
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.
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_cmd``
The command name with which to invoke ``mermaid-cli`` program. The default is ``'mermaid'``; you may need to set this to a full path if it's not in the executable
search path.
``mermaid_phantom_path``
The mermaid command requires 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_output_format``
The output format for Mermaid when building HTML files. This must be either
``'png'`` or ``'svg'``; the default is ``'png'``. Note ``'svg'`` support is very experimental in mermaid.
``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 <http://knsv.github.io/mermaid/#sequence-diagram-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.
=====================
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!
The code will be rendered to a PNG (default) or SVG image (experimental)
(see :confval:`mermaid_output_format`) using `mermaid-cli <http://knsv.github.io/mermaid/#mermaid-cli>`_.
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.
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_cmd``
The command name with which to invoke ``mermaid-cli`` program. The default is ``'mermaid'``; you may need to set this to a full path if it's not in the executable
search path.
``mermaid_phantom_path``
The mermaid command requires 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_output_format``
The output format for Mermaid when building HTML files. This must be either
``'png'`` or ``'svg'``; the default is ``'png'``. Note ``'svg'`` support is very experimental in mermaid.
``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 <http://knsv.github.io/mermaid/#sequence-diagram-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.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Close
Hashes for sphinxcontrib-mermaid-0.1.1.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | 87ed3c52aecb8796824610df8a78d17e301dda3a4048c89958e47a703c23a786 |
|
MD5 | b4f95dd2a9636602a57dd52aa00976e5 |
|
BLAKE2b-256 | a56d560f954e8ac0540a414c0c0e61bf81975a82904ac5909e9f5565f2985002 |
Close
Hashes for sphinxcontrib_mermaid-0.1.1-py2.py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | e63bf9caf8e58d87fb77b0ed43f44e19814ba76b4b8892771ee51f36b6ebb741 |
|
MD5 | 12f6c0b1c9dfcbb99e5a9cf0deca9bd9 |
|
BLAKE2b-256 | 56e6279a8a2715771efd8644f92c8ba2b0ccb72282ee7870f5715f38042b0390 |