PlantUML for Sphinx

Installation

.. code-block::

pip install sphinxcontrib-plantuml

Usage

Add sphinxcontrib.plantuml to your extensions list in your conf.py:

.. code-block:: python

extensions = [
'sphinxcontrib.plantuml',
]

You may also need to specify the plantuml command in your conf.py:

.. code-block:: python

plantuml = 'java -jar /path/to/plantuml.jar'

Instead, you can install a wrapper script in your PATH:

.. code-block:: console

% cat < /usr/local/bin/plantuml
#!/bin/sh -e
java -jar /path/to/plantuml.jar "$@"
EOT
% chmod +x /usr/local/bin/plantuml

Then, write PlantUML text under the .. uml:: (or .. plantuml::)
directive::

.. uml::

   Alice -> Bob: Hi!
   Alice <- Bob: How are you?

or specify path to an external PlantUML file::

.. uml:: external.uml

You can specify height, width, scale and align::

.. uml::
   :scale: 50 %
   :align: center

   Foo <|-- Bar

You can also specify a caption::

.. uml::
   :caption: Caption with **bold** and *italic*
   :width: 50mm

   Foo <|-- Bar

For details, please see PlantUML_ documentation.

.. _PlantUML: http://plantuml.com/

Configuration

plantuml
Path to plantuml executable. (default: 'plantuml')

plantuml_output_format
Type of output image for HTML renderer. (default: 'png')

:png: generate only .png inside
:svg: generate .svg inside with .png inside as a fallback
:svg_img: generate only .svg inside (browser support <svg_img_>)
:svg_obj: generate only .svg inside (browser support <svg_obj_>)
:none: do not generate any images (ignore uml directive)

When svg is inside it will always render full size, possibly bigger
than the container. When svg is inside it will respect container size
and scale if necessary.

plantuml_latex_output_format
Type of output image for LaTeX renderer. (default: 'png')

:svg_pdf: generate .svg and convert it to .pdf (requires registered ImageConverter)
:eps_pdf: generate .eps and convert it to .pdf (requires epstopdf)
:pdf: use svg_pdf if available, fallback to eps_pdf
:eps: generate .eps (not supported by pdflatex)
:png: generate .png
:tikz: generate .latex in the TikZ format
:none: do not generate any images (ignore uml directive)

Because embedded png looks pretty bad, it is recommended
to choose svg_pdf.

An example for the registered ImageConverter would be
sphinxcontrib.inkscapeconverter from sphinxcontrib-svg2pdfconverter.
The first detected converter that supports .svg to .pdf is used.

plantuml_epstopdf
Path to epstopdf executable. (default: 'epstopdf')

.. _svg_img: https://caniuse.com/svg-img
.. _svg_obj: https://caniuse.com/svg

plantuml_syntax_error_image
Should plantuml generate images with render errors. (default: False)

plantuml_cache_path
Directory where image cache is stored. (default: '_plantuml')

plantuml_batch_size
(EXPERIMENTAL)
Run plantuml command per the specified number of images. (default: 1)

If enabled, plantuml documents will be first written to the cache directory,
and rendered in batches. This eliminates bootstrapping overhead of Java
runtime and allows plantuml to leverage multiple CPU cores.

To enable batch rendering, set the size to 100-1000.

Developing

Install the python test dependencies with

.. code-block::

pip install sphinxcontrib-plantuml[test]

In addition the following non-python dependencies are required in order to run the tests:

latexmk

plantuml

texlive

texlive-font-utils

texlive-latex-extra

The tests can be executed using pytest

.. code-block::

pytest

Dependencies of sphinxcontrib-plantuml (4).
Dependency	Optional
Sphinx	false
flake8	true
Pillow	true
pytest	true

Package profile

sphinxcontrib-plantuml

Releases

Release table

PyPI Downloads

Dependencies

Details

Project URLs

Dependencies

Package description