Using Maven for maintaining user documentation [closed]
https://stackoverflow.com/questions/4657284
-
09-10-2019 - |
italiano
english
français
española
中国
日本の
العربية
Deutsch
한국어
Português
RussianQuestion
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:
OTHER TIPS
And in case the site plugin with external docs does not produce a high enough quality, you can use docbook with Maven to produce HTML and PDF output. In fact Sonatype does that for all their books (e.g. Maven: The Complete Reference, Nexus book, M2Eclipse book...) and they are open source so you can see how it all works and copy the setup and modify it for your needs. The advantage of using docbook is that the tooling is pretty good (xmlmind for example) and that it produces print quality books with index, toc and so on.
Oh and since you mentioned it there is also a LaTeX plugin for Maven but I have no experience with it (but quite a bit with LaTeX prior to my Maven usage...)
Another solution is the Maven docbkx plugin for conversion of DocBook into PDF; HTML, etc.
Read this description on how to add the converted DocBook to HTML to a Maven project site, if you would like to see your DocBook content also appear in the Maven generated site.
Interesting related questions:
I have a multi-module maven project in which each module has it's own reference-manual written in docbook format. And then I have a general reference manual, also written in docbook that includes the others so I am re-using the documentation. When I execute mvn site, the project generates HTML and PDF files with all the reference manuals and they are neatly integrated into the maven site. For this I use the docbkx plugin. I think it really rocks. Here is the plugin configuration:
<plugin>
<groupId>com.agilejava.docbkx</groupId>
<artifactId>docbkx-maven-plugin</artifactId>
<executions>
<execution>
<id>docbook-HTML</id>
<phase>pre-site</phase>
<goals>
<goal>generate-html</goal>
</goals>
<!-- HTML configuration -->
<configuration>
<generateToc>false</generateToc>
<targetDirectory>${project.build.directory}/site</targetDirectory>
<htmlCustomization>${basedir}/src/site/docbkx-config/docbook-html.xsl</htmlCustomization>
<htmlStylesheet>./css/apache-maven-fluido-1.3.0.min.css</htmlStylesheet>
<chunkedOutput>false</chunkedOutput>
</configuration>
</execution>
<execution>
<id>docbook-PDF</id>
<phase>pre-site</phase>
<goals>
<goal>generate-pdf</goal>
</goals>
<!-- PDF configuration -->
<configuration>
<generateToc>true</generateToc>
<paperType>A4</paperType>
<imgSrcPath>file:///${basedir}/src/site/resources/</imgSrcPath>
<calloutGraphicsPath>file:///${basedir}/src/site/resources/images/callouts/</calloutGraphicsPath>
<calloutGraphicsExtension>.svg</calloutGraphicsExtension>
<calloutGraphicsNumberLimit>30</calloutGraphicsNumberLimit>
<calloutIconSize>6</calloutIconSize>
<shadeVerbatim>true</shadeVerbatim>
<targetDirectory>${project.build.directory}</targetDirectory>
<foCustomization>${basedir}/src/site/docbkx-config/docbook-fo.xsl</foCustomization>
<!-- <bodyFontFamily>Kaffeesatz</bodyFontFamily>
<monospaceFontFamily>LiberationMono</monospaceFontFamily>
-->
<fonts>
<font>
<name>Kaffeesatz</name>
<style>normal</style>
<weight>normal</weight>
<embedFile>${basedir}/src/fonts/YanoneKaffeesatz-Regular.ttf</embedFile>
<metricsFile>${basedir}/target/fonts/YanoneKaffeesatz-Regular-metrics.xml</metricsFile>
</font>
<font>
<name>LiberationMono</name>
<style>normal</style>
<weight>normal</weight>
<embedFile>${basedir}/src/fonts/LiberationMono-Regular.ttf</embedFile>
<metricsFile>${basedir}/target/fonts/LiberationMono-Regular-metrics.xml</metricsFile>
</font>
<font>
<name>VeraMono</name>
<style>normal</style>
<weight>normal</weight>
<embedFile>${basedir}/src/fonts/VeraMono.ttf</embedFile>
<metricsFile>${basedir}/target/fonts/VeraMono-metrics.xml</metricsFile>
</font>
</fonts>
</configuration>
</execution>
</executions>
<!-- Shared configuration -->
<configuration>
<sourceDirectory>${basedir}/src/site/docbkx</sourceDirectory>
<includes>*.xml</includes>
<xincludeSupported>true</xincludeSupported>
<generatedSourceDirectory>${project.build.directory}/site</generatedSourceDirectory>
<highlightSource>1</highlightSource>
<calloutGraphics>true</calloutGraphics>
<!-- DEFAULT HTML CONFIG -->
<targetDirectory>${project.build.directory}/site</targetDirectory>
<htmlCustomization>src/site/docbook-config/docbook-html.xsl</htmlCustomization>
<htmlStylesheet>css/apache-maven-fluido-1.3.0.min.css</htmlStylesheet>
<!-- // DEFAULT HTML CONFIG -->
</configuration>
</plugin>
You can check out my project site here and you can even download the sources into your computer and see how the whole thing is set up. If you have any questions don't hesitate to reach out.
Hope it helps
Cheers Carlos
