Generate UML diagrams from source (issue #47)

[davidonlaptop]

Context

This patch is in response to issue #47 I've created.

This code uses the UmlGraphDoc maven plugin to automatically insert UML diagrams from the Java sources (which were generated from the avro files). The Builder classes are intentionnally ignored to avoid duplication.

Dependencies

GraphViz (dot) is required in the classpath of the target system in order to reap the benefits from this patch.

However, this patch should be unobtrusive since it is implemented as a maven profile.

Synopsis

# Generate javadoc without diagrams
mvn javadoc:javadoc
# Generate javadoc with diagrams
mvn javadoc:javadoc -P uml-diagrams

Sample Output

Check here for the class diagram, and here for the javadoc.

Feedback expected

Please verify that this does not break things in the other projects like Adam, but I think it should be ok.

Verifications done to test this patch

If you have Docker installed, you can try:

1) Run a new container based on a Java image (Oracle JDK)

david@Ubuntu-1404:~$ docker run -ti --rm=true gelog/java:openjdk7 bash
Unable to find image 'gelog/java:oraclejdk7' locally
Pulling repository gelog/java
4cfed8782477: Download complete 
511136ea3c5a: Download complete 
27d47432a69b: Download complete 
5f92234dcf1e: Download complete 
51a9c7c1f8bb: Download complete 
5ba9dab47459: Download complete 
60b3f525b221: Download complete 
Status: Downloaded newer image for gelog/java:oraclejdk7
root@9593c1f4ad24:/#

2) Then, paste these lines (inside the container)

# Install Maven 
wget https://archive.apache.org/dist/maven/maven-3/3.2.3/binaries/apache-maven-3.2.3-bin.tar.gz
tar -xzf /apache-maven-3.2.3-bin.tar.gz -C /usr/local/
ln -s /usr/local/apache-maven-3.2.3 /usr/local/apache-maven
export PATH="$PATH:/usr/local/apache-maven/bin"
export MAVEN_OPTS="-Xmx512m -XX:MaxPermSize=128m"

# Download modified version of BDG-Formats from GELOG
apt-get update && apt-get install -y git
git clone https://github.com/GELOG/bdg-formats.git /opt/bdg-formats
cd /opt/bdg-formats

3) Scenario 1: A user which does NOT have GraphViz installed, can generate HTML from the javadoc (without diagrams)

root@9593c1f4ad24:/opt/bdg-formats# dot                
bash: dot: command not found

root@9593c1f4ad24:/opt/bdg-formats# mvn javadoc:javadoc
[...]
[INFO] BUILD SUCCESS
[...]

4) Scenario 2: A user which does NOT have GraphViz installed, can try the uml-diagrams profile but it won't work

root@9593c1f4ad24:/opt/bdg-formats# mvn javadoc:javadoc -P uml-diagrams
[...]
[WARNING] Ensure that dot is in your path and that its path does not contain spaces
[...]
[INFO] BUILD SUCCESS
[...]

5) Scenario 3: a user which has GraphViz installed, can generate UML diagrams within the html javadoc

root@9593c1f4ad24:/opt/bdg-formats# apt-get install -y graphviz
[...]
root@9593c1f4ad24:/opt/bdg-formats# which dot
/usr/bin/dot
root@9593c1f4ad24:/opt/bdg-formats# mvn javadoc:javadoc -P uml-diagrams
[...]
[INFO] BUILD SUCCESS

root@9593c1f4ad24:/opt/bdg-formats# ls -l target/site/apidocs/org/bdgenomics/formats/avro/*.png | wc -l
34
root@9593c1f4ad24:/opt/bdg-formats# exit
david@Ubuntu-1404:~$

[AmplabJenkins]

Can one of the admins verify this patch?

[laserson]

Jenkins, add to whitelist

[laserson]

Looks great, @davidonlaptop! I defer to @massie for all things Maven.

[fnothaft]

Merged! Thanks @davidonlaptop!