Plantweb is a project that provides a command line interface, Sphinx directives and an API that allows to render powerful plain text UML diagrams, ASCII diagrams and complex graphs.
It is a Python client for the PlantUML server and thus it can render PlantUML, Graphviz and Ditaa diagrams without the need to install them.
Check out the Examples Gallery.
Plantweb features a local cache that prevents requesting the server for previously rendered diagrams, speeding up building documentation with lots of diagrams.
Finally, being pure Python, non-local rendering, Plantweb is an excellent way to display and render PlantUML, Graphviz and Ditaa diagrams in ReadTheDocs published documentation.
In particular, Ditaa rendering is particularly usefull when using ASCII drawing tools like asciiflow.
sudo pip3 install plantweb
If the content of your file is wrapped by @startxxx
, @endxxx
then
Plantweb is capable of determining the engine to use.
Options are:
Opening | Closure | Engine |
---|---|---|
@startuml |
@enduml |
plantuml |
@startdot |
@enddot |
graphviz |
@startditaa |
@endditaa |
ditaa |
For example, the following Graphviz file mydotfile.dot
:
@startdot
digraph one_node_graph {
node1 -> node2 -> node3
}
@enddot
Can be rendered with:
user@host:~$ plantweb mydotfile.dot
Note
File extensions are irrelevant for Plantweb.
If for some reason your files lack the @startxxx/@endxxx
wrapper you can
still render the file by specifying the engine:
user@host:~$ plantweb --engine=graphviz unwrappeddotfile.dot
Complete options:
user@host:~$ plantweb --help
usage: plantweb [-h] [-v] [--version]
[--engine {auto,plantuml,graphviz,ditaa}]
[--format {auto,svg,png}] [--server SERVER] [--no-cache]
[--cache-dir CACHE_DIR]
sources [sources ...]
Python client for the PlantUML server
positional arguments:
sources source files to render
optional arguments:
-h, --help show this help message and exit
-v, --verbose increase verbosity level
--version show program's version number and exit
--engine {auto,plantuml,graphviz,ditaa}
engine to use to render diagram
--format {auto,svg,png}
diagram export format
--server SERVER server to use for rendering
--no-cache do not use cache
--cache-dir CACHE_DIR
directory to store cached renders
New in version 0.4.0.
Plantweb provides 3 Sphinx directives for rendering diagrams:
.. uml::
Allows to render the content using the PlantUML engine.
Warning
This directive overrides the one provided by sphinxcontrib.plantuml
.
.. graph::
Allows to render the content using the Graphviz engine.
Warning
This directive overrides the one provided by sphinx.ext.graphviz
.
.. diagram::
Note
When using the directives it is NOT recommended nor required to use the
@startxxx
/ @endxxx
tags.
For example:
.. uml::
Alice -> Bob: Authentication Request
Bob --> Alice: Authentication Response
Alice -> Bob: Another authentication Request
Alice <-- Bob: another authentication Response
The above will render:
See also
Check out the Examples Gallery.
New in version 1.0.0.
Directives also support specifying a path to a file to load the content.
For example:
.. uml:: my_uml_diagram.uml
The above will load the file my_uml_diagram.uml
with the content to be
rendered.
You may specify a relative path from the current document or you may specify an
absolute path from where the conf.py
like this:
.. uml:: /diagrams/my_uml_diagram.uml
The above will load the file from the Sphinx documentation root.
alt
: textalign
: “left”, “center”, or “right”The alignment of the image. It control an image’s horizontal alignment, allowing the image to float and have the text flow around it.
Warning
This behavior could be changed by your theme.
target
: text (URI or reference name)name_
).For example:
.. uml::
:alt: This is a nice UML diagram. Indeed.
:align: left
:target: #options
actor Foo1
boundary Foo2
control Foo3
entity Foo4
database Foo5
Foo1 -> Foo2 : To boundary
Foo1 -> Foo3 : To control
Foo1 -> Foo4 : To entity
Foo1 -> Foo5 : To database
Render as:
Warning
Plantweb directives doesn’t have any height
, width
or scale
options. In this age of responsive design there shouldn’t be the need to
define presentational values in the content. Also, being diagrams, you
should always maximize viewing space.
If your images overflow, override your theme or use a theme that already supports responsive images:
/* Responsive images */
object[type="image/svg+xml"], img {
max-width: 100%;
height: auto;
}
To enable the directives add 'plantweb.directive'
to your extensions in
your Sphinx’s conf.py
:
extensions = [
# ... More extensions,
'plantweb.directive'
]
If you want to configure the extension you can create the variable
plantweb_defaults
in your Sphinx’s conf.py
:
# Plantweb configuration
plantweb_defaults = {
'server': 'http://myserver.com/plantuml/'
}
Please note that the above configuration will have the higher priority as
explained in Overriding Defaults. Nevertheless the defaults resolution mechanism
is still considered, that is, the .plantwebrc
files will still override
other keys if present.
There are 2 main functions, both Python 2.7 and 3.5 compatible:
render()
allows to render content directly.
from plantweb.render import render
CONTENT = """
actor Foo1
boundary Foo2
control Foo3
entity Foo4
database Foo5
Foo1 -> Foo2 : To boundary
Foo1 -> Foo3 : To control
Foo1 -> Foo4 : To entity
Foo1 -> Foo5 : To database
"""
if __name__ == '__main__':
print('==> INPUT:')
print(CONTENT)
output = render(
CONTENT,
engine='plantuml',
format='svg',
cacheopts={
'use_cache': False
}
)
print('==> OUTPUT:')
print(output)
render_file()
allows to render files.
from plantweb.render import render_file
CONTENT = """
digraph finite_state_machine {
rankdir=LR;
size="8,5"
node [shape = doublecircle]; LR_0 LR_3 LR_4 LR_8;
node [shape = circle];
LR_0 -> LR_2 [ label = "SS(B)" ];
LR_0 -> LR_1 [ label = "SS(S)" ];
LR_1 -> LR_3 [ label = "S($end)" ];
LR_2 -> LR_6 [ label = "SS(b)" ];
LR_2 -> LR_5 [ label = "SS(a)" ];
LR_2 -> LR_4 [ label = "S(A)" ];
LR_5 -> LR_7 [ label = "S(b)" ];
LR_5 -> LR_5 [ label = "S(a)" ];
LR_6 -> LR_6 [ label = "S(b)" ];
LR_6 -> LR_5 [ label = "S(a)" ];
LR_7 -> LR_8 [ label = "S(b)" ];
LR_7 -> LR_5 [ label = "S(a)" ];
LR_8 -> LR_6 [ label = "S(b)" ];
LR_8 -> LR_5 [ label = "S(a)" ];
}
"""
if __name__ == '__main__':
infile = 'mygraph.dot'
with open(infile, 'wb') as fd:
fd.write(CONTENT.encode('utf-8'))
print('==> INPUT FILE:')
print(infile)
outfile = render_file(
infile,
renderopts={
'engine': 'graphviz',
'format': 'png'
},
cacheopts={
'use_cache': False
}
)
print('==> OUTPUT FILE:')
print(outfile)
New in version 0.3.0.
The defaults defined in DEFAULT_CONFIG
will be used unless overridden
by the user.
To set a different default configuration create a JSON file .plantwebrc
in your git repository root or in your home, as defined in
DEFAULTS_PROVIDERS
.
For example:
{
"server": "http://mydomain.com/plantuml/",
"cache_dir": "~/.cache/plantweb",
"engine": "plantuml",
"format": "svg",
"use_cache": true
}
See also
If you require:
Please consider running a PlantUML server in your local network or private server. The easiest way is to do it is using the official PlantUML Docker image:
docker pull plantuml/plantuml-server
docker run --detach --publish 8080:8080 plantuml/plantuml-server
For more information about the PlantUML server visit:
The public PlantUML server used by Plantweb by default is run by a group of volunteers for pure love.
Please consider donating to the project through Paypal, Patreon or Flattr.
sphinx.ext.inheritance_diagram
that
also uses Graphviz to use Plantweb.Copyright (C) 2016-2017 Carlos Jenkins
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing,
software distributed under the License is distributed on an
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
KIND, either express or implied. See the License for the
specific language governing permissions and limitations
under the License.
Logo derived from work by VisciousSpeed under Public Domain.