Metadata-Version: 2.1
Name: sphinxcontrib-mermaid
Version: 0.8.1
Summary: Mermaid diagrams in yours Sphinx powered docs
Home-page: https://github.com/mgaitan/sphinxcontrib-mermaid
Download-URL: https://pypi.python.org/pypi/sphinxcontrib-mermaid
Author: Martín Gaitán
Author-email: gaitan@gmail.com
License: BSD
Platform: any
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: BSD License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Classifier: Topic :: Documentation
Classifier: Topic :: Utilities
Requires-Python: >=3.7
License-File: LICENSE.rst

.. image:: https://github.com/mgaitan/sphinxcontrib-mermaid/actions/workflows/test.yml/badge.svg
    :target: https://github.com/mgaitan/sphinxcontrib-mermaid/actions/workflows/test.yml

This extension allows you to embed `Mermaid <https://mermaid-js.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 <https://github.com/mermaidjs/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 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 hierarchy 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:



Or directly the module::

    .. autoclasstree:: sphinx.util




Installation
------------

You can install it using pip

::

    pip install sphinxcontrib-mermaid

Then add ``sphinxcontrib.mermaid`` in ``extensions`` list of your project's ``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``

``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/.  The default is ``"9.4.0"``. If you need a newer version, you'll need to add the custom initialization. See below. 

  If it's set to ``""``, the lib won't be automatically included from the CDN service and you'll need to add it as a local
  file in ``html_js_files``. For instance, if you download the lib to `_static/js/mermaid.js`, in ``conf.py``::


    html_js_files = [
       'js/mermaid.js',
    ]


``mermaid_init_js``

  Mermaid initilizaction code. Default to ``"mermaid.initialize({startOnLoad:true});"``.



``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_cmd_shell``

   When set to true, the ``shell=True`` argument will be passed the process execution command.  This allows commands other than binary executables to be executed on Windows.  The default is false.

``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 <https://mermaid-js.github.io/mermaid/#/mermaidAPI?id=configuration>`_

``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.


Markdown support
----------------

You can include Mermaid diagrams in your Markdown documents in Sphinx.
You just need to setup the `markdown support in Sphinx <https://www.sphinx-doc.org/en/master/usage/markdown.html>`_ via
`myst-parser <https://myst-parser.readthedocs.io/>`_
. See a `minimal configuration from the tests <https://github.com/mgaitan/sphinxcontrib-mermaid/blob/master/tests/roots/test-markdown/conf.py>`_

Then in your `.md` documents include a code block as in reStructuredTexts::


 ```{mermaid}

     sequenceDiagram
       participant Alice
       participant Bob
       Alice->John: Hello John, how are you?
 ```

Building PDFs on readthedocs.io
-----------------------------------

In order to have Mermaid diagrams build properly in PDFs generated on readthedocs.io, you will need a few extra configurations.  

1. In your ``.readthedocs.yaml`` file (which should be in the root of your repository) include a ``post-install`` command to install the Mermaid CLI: ::

    build:
      os: ubuntu-20.04
      tools:
        python: "3.8"
        nodejs: "16"
      jobs:
        post_install:
          - npm install -g @mermaid-js/mermaid-cli

 Note that if you previously did not have a ``.readthedocs.yaml`` file, you will also need to specify all targets you wish to build and other basic configuration options.  A minimal example of a complete file is: ::

    # .readthedocs.yaml
    # Read the Docs configuration file
    # See https://docs.readthedocs.io/en/stable/config-file/v2.html for details

    # Required
    version: 2

    # Set the version of Python and other tools you might need
    build:
      os: ubuntu-20.04
      tools:
        python: "3.8"
        nodejs: "16"
      jobs:
        post_install:
          - npm install -g @mermaid-js/mermaid-cli

    # Build documentation in the docs/ directory with Sphinx
    sphinx:
       configuration: docs/conf.py

    # If using Sphinx, optionally build your docs in additional formats such as PDF
    formats:
      - epub
      - pdf

    python:
       install:
       - requirements: docs/requirements.txt

2. In your documentation directory add file ``puppeteer-config.json`` with contents: ::

    {
      "args": ["--no-sandbox"]
    }
   

3. In your documentation ``conf.py`` file, add: ::

    mermaid_params = ['-p' 'puppeteer-config.json']

Changelog
---------

0.8.1 (Feb 9, 2023)
+++++++++++++++++++++

- Default to Mermaid 9.4.0 as 10.0 introduced incompatible changes. 
  See `the discussion <https://github.com/mermaid-js/mermaid/discussions/4148>`_. 

0.8 (Feb 9, 2023)
+++++++++++++++++++++

- Moved CI to Github Actions
- Make the class diagram reproducible
- Allow the user to change the JS priority
- Drop support for Python 3.6
- Black formatting

See `full set of changes <https://github.com/mgaitan/sphinxcontrib-mermaid/compare/0.7.1...0.8>`_.


0.7.1 (July 17, 2021)
+++++++++++++++++++++

- Update docs and tests for markdown support


0.7 (May 31, 2021)
++++++++++++++++++++++++++

- Add compatibility with Sphinx 4.0
- `mermaid_init_js` is now included in an standard way.
- Documented how to use in Markdown documents


0.6.3 (February 21, 2021)
++++++++++++++++++++++++++

- Make it compatible with recent Sphinx versions
- Add basic (real) tests (So I stop breaking it!)


0.6.2 (February 18, 2021)
++++++++++++++++++++++++++

- fix regression
- setup travis


0.6.1 (February 8, 2021)
++++++++++++++++++++++++++

- Fix a problem when called mermaid-cli
- Fix typos on documentation
- Improve internal code formatting (via black)

0.6.0 (January 31, 2021)
++++++++++++++++++++++++++

- Drop support for Python version older than 3.6.
- Allow to include javascript lib locally
- Initialization code is now customizable
- The default version included from the CDN is always the latest available.


0.5.0 (September 24, 2020)
++++++++++++++++++++++++++

- Added mermaid_cmd_shell. Useful for Windows user.
- Reimplement inheritance diagrams.
- Fix UnicodeEncodeError on Python 2

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 <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
