Plantweb¶

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
Usage
Overriding Defaults
PlantUML Server
Development
TODO
License

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

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
}

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

http://plantuml.com/server.html

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.

Development ¶

TODO ¶

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

License ¶

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.

Opening	Closure	Engine
`@startuml`	`@enduml`	plantuml
`@startdot`	`@enddot`	graphviz
`@startditaa`	`@endditaa`	ditaa

Contents

Next topic

This Page

Plantweb¶

Installation ¶

Usage ¶

Command Line Interface ¶

Sphinx Directives ¶

Options ¶