Search code examples
pdfmaven-2documentationlatexdocbook

Using Maven for maintaining user documentation

We are using Maven for building a Java server-style application. It consists of several modules (in a single Maven "reactor") which can be plugged together to generate a final product (essentially a .jar) with the features enabled that the customer needs. All the internals are documented using JavaDoc and all, but that's not what you can give to the customer to find out how to get the thing running. Currently we have an OpenOffice document which serves as end-user documentation.

I'd like to integrate this documentation into the Maven build process where each module's documentation is maintained (hand-edited) together with the Module's sources and the final document can reference the required Module documentation sections, add some friendly foreword and, if possible at all, can reference into the JavaDocs. Ultimately, the document should be output as a PDF.

Is there any experience on Maven plugins can help with this? Is DocBook the right tool? Maybe Latex? Or something completely different? A sound "stick with OpenOffice and some text blocks" could be an answer, too.

Solution

  • I'm assuming you haven't looked at the Maven site documentation generation yet with the maven-site-plugin. It's pretty robust and will allow you to incorporate and include the JavaDoc generation as well as the content from your OpenOffice document.

    While the site documentation doesn't output as a PDF, it does however output as a static HTML website that has lots of capabilities built in. Using Maven profiles, you could configure Maven to generate one site for internal use that includes Surefire test results and other reports for checks like Checkstykle and PMD. In another profile, you could configure it to only generate the documentation necessary for distribution to the clients that doesn't include the internal reports that the clients may not care about.

    One note though, much of the site documentation generation is changing for Maven 3. While most of Maven 3 is backwards compatible with Maven 2, be mindful of the reporting changes for Maven 3. Check out these links: