This plugin allows you to define UML diagrams directly into rst or md documents using the great PlantUML tool.
It gets the content of uml directive, passes it to the external program PlantUML and then links the generated image to the document.
You need to install PlantUML (see the site for details) and Graphviz 2.26.3 or later. The plugin expects a program plantuml in the classpath. If not installed by your package manager, you can create a shell script and place it somewhere in the classpath. For example, save te following into /usr/local/bin/plantuml (supposing PlantUML installed into /opt/plantuml):
#!/bin/bash
java -jar /opt/plantuml/plantuml.jar ${@}For Gentoo there is an ebuild at http://gpo.zugaina.org/dev-util/plantuml/RDep: you can download the ebuild and the files subfolder or you can add the zugaina repository with _layman (reccomended).
Add plantuml to plugin list in pelicanconf.py. For example:
PLUGINS = [ "sitemap", "plantuml" ]
One loaded the plugin register also the Pyhton-Markdown extension.
Use the uml directive to start UML diagram description. It is not necessary to enclose diagram body between @startuml and @enduml directives: they are added automatically before calling plantuml.
In addition to class and alt options common to all images, you can use the format option to select what kind of image must be produced. At the moment only png and svg are supported; the default is png.
Please note that the format option in not recognized by the plantuml extension of rst2pdf utility (call it with -e plantuml.py) so if you use it you can get errors from that program.
For use with the Pyhton-Markdown syntax, the UML block must be enclose with ::uml:::
::uml:: [format=...] [classes=...] [alt=...]
PlantUML script
::end-uml::Please keep a blank line before ::uml:: and after ::end-uml:: to be sure that the UML code will be correctly recognized. See Examples for more details.
With MD syntax options must be specified in the same line as the opening :uml::, with the order format, classes anmd alt. The general syntax for option is
option="value"
Option can be enclosed with single or double quotes, as you like. Options defaults are the same as for the rst plugin.
The plugin pandoc_reader sends the Markdown body to the pandoc tool which has it's own Markdown parser, written in Haskell language: Python_ plugins manipulating Markdown posts (such this) are not used because the entire body id passed to pandoc without any iteraction by Pelican.
For those who are using the pandoc_reader plugin and wants to include PlantUML diagrams, use the pandoc-plantuml script (only *nix, sorry): it is a wrapper for filtering the code blocks parsed by pandoc before
writing out the converted file. It is an adaption of the great work by Kurt Bonne for his pandoc-plantuml-filter.
To use it, copy the pandoc-plantuml file in a subdirectory of your pelican project (for example pandoc_extensions) and make sure it is executable (chmod +x pandoc-plantuml).
In the pelicanconf.py configure the needed plugins:
PLUGINS = ['pandoc_reader'] // Yes, plantuml plugin non necessary
PANDOC_ARGS = ['--filter=pandoc_extensions/pandoc-plantuml']In Markdown posts use the following syntax to include PlantUML diagrams:
```plantuml
@startuml
Alice -> Bob: Authentication Request
Bob --> Alice: Authentication Response
Alice -> Bob: Another authentication Request
Alice <-- Bob: another authentication Response
@enduml
```Rendered images will bu put in the output/images folder.
NOTE: pandoc-plantuml is broken from pandoc 1.16 cause an API change in pandoc Image function. I'm working on a fix but in the meanwhile use a version of pandoc prior to 1.16 .
The plugin can produce debugging informations to help to locate errors. To enable debugging execute pelican in debug mode:
make DEBUG=1 html
Sequence diagram (from PlantUML site):
.. uml::
:alt: Sample sequence diagram
participant User
User -> A: DoWork
activate A #FFBBBB
A -> A: Internal call
activate A #DarkSalmon
A -> B: << createRequest >>
activate B
B --> A: RequestCreated
deactivate B
deactivate A
A -> User: Done
deactivate AOutput:
Same diagram with Python-Markdown_ syntax:
::uml:: format="png" alt="Sample sequence diagram"
participant User
User -> A: DoWork
activate A #FFBBBB
A -> A: Internal call
activate A #DarkSalmon
A -> B: << createRequest >>
activate B
B --> A: RequestCreated
deactivate B
deactivate A
A -> User: Done
deactivate A
::end-uml::Another example from PlantUML site (activity diagram):
.. uml::
start
:ClickServlet.handleRequest();
:new page;
if (Page.onSecurityCheck) then (true)
:Page.onInit();
if (isForward?) then (no)
:Process controls;
if (continue processing?) then (no)
stop
endif
if (isPost?) then (yes)
:Page.onPost();
else (no)
:Page.onGet();
endif
:Page.onRender();
endif
else (false)
endif
if (do redirect?) then (yes)
:redirect process;
else
if (do forward?) then (yes)
:Forward request;
else (no)
:Render page template;
endif
endif
stopGenerated image:
