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
-------------
.. confval:: 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.
.. confval:: 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.
.. confval:: 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.
.. confval:: 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>`_
.. confval:: mermaid_verbose
Use the verbose mode when call mermaid-cli, and show its output in the building
process.
Acknowledge
-----------
Most of the code
=====================
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
-------------
.. confval:: 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.
.. confval:: 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.
.. confval:: 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.
.. confval:: 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>`_
.. confval:: mermaid_verbose
Use the verbose mode when call mermaid-cli, and show its output in the building
process.
Acknowledge
-----------
Most of the code
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.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | c7760324f80f63b73b7c09813c68a35bdf222b7a61dd36a72e9f4f5e2102daae |
|
MD5 | 70c00953373adc5aa64729df4fc9efae |
|
BLAKE2b-256 | dddfbd312aacf0bb97557d16d074b8db0059666b56abbbf74beffa86c6e39acc |
Close
Hashes for sphinxcontrib_mermaid-0.1-py2.py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | c43511cbb176f1d9e4aa9ffc2ee5d7e7e6ccf936d09a9df5012e635116cc9c54 |
|
MD5 | b4e8704c009e29ab90f300778e23abc3 |
|
BLAKE2b-256 | 72429934e3a371ee5e12dd515ea81621c622db48891b8d1c4c9cf5ef283b4f49 |