Skip to content

Latest commit

 

History

History
216 lines (145 loc) · 6.65 KB

Readme.rst

File metadata and controls

216 lines (145 loc) · 6.65 KB
Raw

PlantUML plugin for Pelican rst and md documents

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.

Contents

Installation

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

Usage

Add plantuml to plugin list in pelicanconf.py. For example:

PLUGINS = [ "sitemap", "plantuml" ]

One loaded the plugin register also the Pyhton-Markdown extension.

RST usage

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.

MD usage

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.

For pandoc_reader plugin users

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 .

Debugging

The plugin can produce debugging informations to help to locate errors. To enable debugging execute pelican in debug mode:

make DEBUG=1 html

Examples

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 A

Output:

Sample sequence diagram

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

  stop

Generated image:

Sample activity diagram