Plantweb

_images/logo.png

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.

Installation

sudo pip3 install plantweb

Usage

Command Line Interface

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

Sphinx Directives

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::
Allows to render the content using the Ditaa engine.

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.

Options

alt: text
Alternate text: a short description of the image, displayed by applications that cannot display images, when the user over the image with the cursor or spoken by applications for visually impaired users.
align: "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)
Makes the image into a hyperlink reference ("clickable"). The option argument may be a URI (relative or absolute), or a reference name with underscore suffix (e.g. 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:

This is a nice UML diagram. Indeed.

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

Sphinx Setup

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.

Python API

There are 2 main functions, both Python 2.7 and 3.4 compatible:

  1. 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)
    
  2. 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)
    

Overriding Defaults

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

PlantUML Server.

PlantUML Server

If you require:

  • Guaranteed uptime.
  • To render confidential diagrams.
  • To speed up rendering in your intranet.
  • Or you simply want to be nice and unload the public server.

Please consider installing a PlantUML server in your local network or private server:

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.

TODO

  • We should be able to monkey patch sphinx.ext.inheritance_diagram that also uses Graphviz to use Plantweb.

License

Copyright (C) 2016 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.