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
default properties file
I have a
defaults.properties file in a standard location that has a variable populated at build time:
Inside the file is a line – there’s actually more than one, but for simplicity’s sake:
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
<siteDirectory/> tag; it’s pointing to the non-default location
target/src/site – based on the output of the 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.
I’ve tied everything together and I run my maven goal:
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.