Using Maven for User Documentation

Question

We use Maven to create a Java server style application. It consists of several modules (in one Maven reactor) that can be connected together to create the final product (mainly .jar) with functions that the client may need. All internal documents are documented using JavaDoc and all, but this is not something you can give the client to find out how to get this working. We currently have an OpenOffice document that serves as documentation for end users.

I would like to integrate this documentation into the Maven build process, where each module documentation is maintained (manually edited) along with the module sources, and the final document can refer to the necessary sections of the module documentation, add friendly introductions and, if possible at all, can refer to JavaDocs. Ultimately, the document should be output as a PDF.

Are there any impressions of the Maven plugins? Is DocBook the right tool? Maybe latex? Or something completely different? A sound “stick with OpenOffice and some text blocks” might also be the answer.

Answer 1

, Maven, maven-site-plugin. JavaDoc, OpenOffice.

PDF, , , HTML- . Maven, Maven , Surefire Checkstykle PMD. , , , , .

: Maven 3. Maven 3 Maven 2, Maven 3. :

• maven-site-plugin Maven 3

Answer 2

, docbook Maven HTML PDF . Sonatype (, Maven: The Complete Reference, Nexus book, M2Eclipse book...), , , , . docbook , (, xmlmind) , ..

, , LaTeX Maven, ( LaTeX Maven...)

Answer 3

Maven docbkx DocBook PDF; HTML ..

, DocBook HTML Maven, DocBook Maven .

:

• XML DocBook?.

Answer 4

maven, , docbook. , docbook, , . mvn-, HTML PDF , maven. docbkx. , . :

            <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>

, , . - , .

,