1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
|
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 <<EOT > /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 </img>
:svg: generate .svg inside <object/> with .png inside </img> as a fallback
:svg_img: generate only .svg inside <img/> (`browser support <svg_img_>`_)
:svg_obj: generate only .svg inside <object/> (`browser support <svg_obj_>`_)
:none: do not generate any images (ignore uml directive)
When svg is inside <object/> it will always render full size, possibly bigger
than the container. When svg is inside <img/> 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
|
