PlantUML is a cool tool to integrate UML and Ditaa diagrams easily by a short text syntax into your documentation. The source code for a UML diagram may look like this (example taken from PlantUML’s homepage):
@startuml path/to/image.png Bob -> Alice : hello Alice --> Bob : OK @enduml
PlantUML will generate a PNG image and store it to the given path.
There are two big points for this tool to make it very productive:
- You can write the diagrams in any editor very quickly. You cannot tweak the layout of elements, which makes creating diagrams even faster.
- You can write the diagram in any text file and let PlantUML find that location and create the image. There is no need to switch tools or bother with the administration of files: documentation file, image file, and possibly the image source file.
The last point is even cooler if you have a look on tools for which a PlantUML plugin is provided. So there is a good chance that you can use PlantUML with many tools you use.
Let’s have a look at the integration of PlantUML with Maven to support editing diagrams the PlantUML-way in Java source code and site documentation.
Javadoc
Write a diagram to a Java source file
First let’s add a diagram to a Java source file and reference it from its Javadoc.
package de.smartics.bar;
/*
* @startuml de/smartics/bar/doc-files/image.png
* Bob -> Alice : hello
* Alice --> Bob : OK
* @enduml
*/
/**
* TEXT TEXT TEXT ...
*
* <img src="doc-files/image.png"/>
*/
public class Foo {
...
}
Please note that we place the image above the Javadoc comment (other than shown in the example on the homepage of PlantUML), since static analyzers otherwise will have difficulties in mapping the comment to the Java element and issue a warning.
To preserve the directory structure we also reproduce the package path to store the generated image in the appropriate subfolder. Placing images in a doc-files subfolder in a package folder is the intended way of adding images to the API documentation.
Running with Maven
The team of the PlantUML tool also provides integration with Maven in form of the Maven PlantUML Plugin. One tip: Add two executions to build images in the case of the site and the javadoc artifact.
<plugin>
<groupId>com.github.jeluard</groupId>
<artifactId>maven-plantuml-plugin</artifactId>
<version>7940</version>
<configuration>
<sourceFiles>
<directory>${basedir}/src/main/java</directory>
<includes>
<include>**/*.java</include>
</includes>
</sourceFiles>
</configuration>
<executions>
<execution>
<id>plantuml-javadoc-site</id>
<goals>
<goal>generate</goal>
</goals>
<phase>pre-site</phase>
<configuration>
<outputDirectory>${basedir}/target/site/apidocs</outputDirectory>
</configuration>
</execution>
<execution>
<id>plantuml-javadoc</id>
<goals>
<goal>generate</goal>
</goals>
<phase>generate-sources</phase>
<configuration>
<outputDirectory>${basedir}/target/apidocs</outputDirectory>
</configuration>
</execution>
</executions>
</plugin>
cycles and you cannot rely on them without writing a plugin that explicitly tests that the generated image are up-to-date.
Maven Site
Write a diagram for the Maven site
Adding a diagram to a XDoc document is also very easy:
<document>
<properties>
<title>my-title</title>
</properties>
<body>
<section name="my-title">
<p>
TEXT TEXT TEXT ...
</p>
<!--
@startuml myimage.png
X -> Alice : hello
Alice -> X : OK
@enduml
-->
<img src="myimage.png"/>
</section>
</body>
</document>
Please note that a XML comment puts constraints on the syntax being used within the diagram. Two consecutive dashes (--, e.g. -->) are not allowed in a comment. This seems to be an unresolved issue.
A workaround is to use a div element that is hidden:
<div style="visibility:hidden"> @startuml diagrams/project-overview.png X -> Alice : hello Alice --> X : OK @enduml </div>
Running with Maven
The following configuration of the Maven PlantUML Plugin allows to place text files (with the extension .xml or .txt) within the site folder to generate image files to be referenced from XDoc files.
<plugin>
<groupId>com.github.jeluard</groupId>
<artifactId>maven-plantuml-plugin</artifactId>
<version>7940</version>
<configuration>
<verbose>false</verbose>
<format>png</format>
</configuration>
<executions>
<execution>
<id>plantuml-site</id>
<goals>
<goal>generate</goal>
</goals>
<phase>generate-sources</phase>
<configuration>
<sourceFiles>
<directory>${basedir}/src/site</directory>
<includes>
<include>**/*.xml</include>
<include>**/*.txt</include>
</includes>
</sourceFiles>
<outputDirectory>${basedir}/target/site</outputDirectory>
</configuration>
</execution>
</executions>
</plugin>
Our default folder for text files containing only PlantUML diagrams is src/site/plantuml.
And Confluence?
For Confluence the free add-on PlantUML for Confluence to add diagrams with PlantUML to your wiki.
More Add-ons for Software Developers?
The projectdoc Toolbox for Confluence supports agile team in their task to communicate with stakeholders. For instance developers need to
- communicate the architecture of a software system,
- provide user documentation for Java libraries or Maven plugins
- or simply want to keep a journal to track interesting ideas and findings.
For all of that the projectdoc Toolbox provides macros and doctypes (also know as templates or blueprints) to make these tasks much easier.
Here is some information to get you started:
