Producing Dynamic Documentation With Maven

I’ve always found it a bit frustrating to have build artifact information only in the build artifacts themselves. This isn’t a complaint about any technology per se, but I find maven can tend to be a bit awkward when you’re trying to ensure consistent and correct version information in internal properties files, artifacts (sure, it’s out-of-the-box with maven) and mvn site.

default properties file

I have a defaults.properties file in a standard location that has a variable populated at build time:

src/main/resources/spring/defaults.properties

Inside the file is a line – there’s actually more than one, but for simplicity’s sake:

component.build.revision=%VERSION%

This is simple enough to replace with google’s excellent maven-replacer-plugin, however I wanted to have the same %VERSION% style parameter to be replaced in parallel with component documentation. More on how I did this below.

markdown papers / site configuration

You should check it out if you’re considering using markdown for your documentation. If you’re not familiar with markdown, check out Daring Fireball for more information. BTW, this blog’s source is markdown!

At a minimum you’ll need to setup two directories and two files (note the .md extension for markdown):

src/site/
src/site/site.xml
src/site/markdown/
src/site/markdown/index.md

There’s nothing out of the ordinary for the site.xml file, and the index.md file is a standard markdown document.

Add something similar to this to your pom.xml file:

Note the <siteDirectory/> tag; it’s pointing to the non-default location target/src/site – based on the output of the maven replacer plugin:

maven-replacer-plugin

The trick here is to have the maven replacer plugin do its replacement on two separate executions, but have them tied to the same phase:

This will allow you to replace only transient data in your target/ directory, so generating a build or building the site documentation won’t cause your source files to have modifications.

site skin

I’ve tied everything together and I run my maven goal:

mvn package

And I get:

Yikes. I find this looks too busy and definitely blander than vanilla. Blander. So long, default skin.

You can use the maven-fluido-skin by adding this to your site.xml:

<skin>
    <groupId>org.apache.maven.skins</groupId>
    <artifactId>maven-fluido-skin</artifactId>
    <version>1.0</version>
</skin>

<custom>
    <fluidoSkin>
        <topBarEnabled>true</topBarEnabled>
        <topBarIcon>
            <name>Shape Without Form Build %VERSION%</name>
            <alt>Shape Without Form!</alt>
            <href>/index.html</href>
        </topBarIcon>
        <sideBarEnabled>false</sideBarEnabled>
    </fluidoSkin>
</custom>

I don’t like the side bar, and I really like the <topBarEnabled\> option; so I’d recommend playing around! Anyways, check out the result:

I really like the pattern I’ve cobbled together here; I find I can keep documentation and code in-sync with minimal effort once this is set up. And it’s nice to be able to have up-to-date documentation ready on SNAPSHOT builds for anyone that’s interested in new features or that may be reviewing your documentation pre-release. It’s also really nice to have your applications have access to the information that identifies their build-time parameters. That has proved useful when debugging multiple deployed war files in containers.

Anyways, I hope this helps someone! Let me know if it does in the comments below.

Paste Filename Into Any Open File Dialog on the Mac

In any open file dialog; to jump directly to the folder a file may be located in:

Command-Shift-G

This is probably old hat for most apple folks, but an annoyance for many. I do this so often it’s robotic but someone was shoulder surfing with me and asked “How’d ja do that?”. I figured I’d share.