PlantUML & Maven - Enrich your project's documentation

As read in previous post  "PlantUML a DSL for creating UML Diagram quick & easy", plantUML is a text based Domain Specific Language (DSL) that helps who need to design UML diagrams, offering also a good integration in IDE like  Eclipse and Netbeans 

Another its great feature is the integration with maven that allow us to put our plantUML files within our projects,  generating diagrams  during a project's lifecycle phase (e.g. during site generation), or upon a goal's execution

The maven plantuml plugin is very easy to use, below a typical usage example:

Usage from Maven:

    <plugin>
      <groupId>com.github.jeluard</groupId>
      <artifactId>plantuml-maven-plugin</artifactId>
      <version>7941</version>
      <configuration>
        <sourceFiles>
          <directory>${basedir}</directory>
          <includes>
            <include>src/main/plantuml/**/*.puml</include>
          </includes>
        </sourceFiles>
      </configuration>
      <dependencies>
        <dependency>
          <groupId>net.sourceforge.plantuml</groupId>
          <artifactId>plantuml</artifactId>
          <version>7976</version>
        </dependency>
      </dependencies>
    </plugin>

Then execute command 

mvn clean com.github.jeluard:plantuml-maven-plugin:generate

That will generate the diagrams (by default the format is .png) in folder  ${basedir}/target/plantuml 

Add UML Diagrams to project's site

As you know from maven is possible generate the project's site this is a very useful feature (for me fundamental) that allow us to make a well defined,well organized  as well as standard project documentation.

Using plantuml maven plugin we can enrich such documentation with UML diagrams. Since maven site plugin allow also to adding extra resources including them in a resources directory as shown below

+- src/
   +- site/
      +- resources/ 
         +- images/
            +- diagram1.jpg

will be enough to configure the plantuml plugin so that the output will be generated in images directory. For this purpose is available the outputDirectory parameter so we have to update configuration as shown below

Configure output directory

    <plugin>
      <groupId>com.github.jeluard</groupId>
      <artifactId>plantuml-maven-plugin</artifactId>
      <version>7941</version>
      <configuration>
       <outputDirectory>${basedir}/src/site/resources/images</outputDirectory>
        <sourceFiles>
          <directory>${basedir}</directory>
          <includes>
            <include>src/main/plantuml/**/*.puml</include>
          </includes>
        </sourceFiles>
      </configuration>
      <dependencies>
        <dependency>
          <groupId>net.sourceforge.plantuml</groupId>
          <artifactId>plantuml</artifactId>
          <version>7976</version>
        </dependency>
      </dependencies>
    </plugin>

Finally we can generate graph and site  executing:

> mvn com.github.jeluard:plantuml-maven-plugin:generate site:site

Publish UML Diagrams to Confluence

Atlassian Confluence is an entreprise wiki & team collaboration software that has rapidly become a first class citizen in Open Source ecosystem.

In my company we use confluence to share technical documentation, so i've developed the maven-confluence-plugin  to allow to generate &  publish documentation on it.

The plugin provides a lot of features (for further details go to site documentation). In the basic (simplest) configuration it relies upon the following directories layout

+- src/
   +- site/
      +- confluence/ 
         +- children/
         +- attachments/
            +- diagram1.puml
         +- template.confluence

where template.confluence will contain the confluence wiki markup, while each file present in children will be added as page's child and each file present in attachments will be attached to the page.

Assuming that we have our diagram described in file diagram1.puml, in the same way previously described we can add UML Diagrams to Confluence's pages simply configuring both plugins as shown below

Maven Confluence plugin basic configuration

<plugin>
 <groupid>org.bsc.maven</groupid>
 <artifactid>maven-confluence-reporting-plugin</artifactid>
 <version>3.4.3</version>
        
 <configuration>
  <serverid>softphone-server</serverid>
  <endpoint>_confluence_uri_/rpc/xmlrpc</endpoint>
  <spacekey>_confluence_space_key_</spacekey>
  <parentpagetitle>_confluence_parent_page_</parentpagetitle>
  <title>_my_page_title_</title>
  <wikifilesext>.confluence</wikifilesext>
 </configuration>
</plugin>

PlantUML plugin configuration

  <plugin>
      <groupId>com.github.jeluard</groupId>
      <artifactId>plantuml-maven-plugin</artifactId>
      <version>7941</version>
      <executions>
      <execution>
       <goals><goal>generate</goal><goals>
       <phase>generate-resources</phase>
      </execution>
     </executions>
      <configuration>
        <outputInSourceDirectory>true</outputInSourceDirectory>       
        <sourceFiles>
          <directory>${basedir}/src/site/confluence/attachments</directory>
          <includes>
            <include>diagram1.puml</include>
          </includes>
        </sourceFiles>
      </configuration>
      <dependencies>
        <dependency>
          <groupId>net.sourceforge.plantuml</groupId>
          <artifactId>plantuml</artifactId>
          <version>7976</version>
        </dependency>
      </dependencies>
</plugin>

Wiki fragment that refer to UML Diagram in template.confluence 

{section}
{column:width=30%}
|| Fig. 1 - My First UML Diagram ||
|!${pageTitle}^diagram1.png!|
{column}
{section}

Finally we can generate graph, page and publish all to confluence executing:

> mvn generate-resources confluence-reporting:deploy

Conclusion

Goal of this article is to give just an idea of the potential of using of maven with plantUML.

The documentation of own work is a fundamental step in professional growing. Often documentation is considered by developers only as a boring and time consuming task, but absolutely it isn't so. However having possibility to write documentation without moving out from development environment probably this task should become easier.
Both "maven site plugin" and "maven confluence plugin" accomplish this requirement , moreover they allow also to keep in sync,  documentation with project  version, joining it with the project's lifecycle.