Maven Documentation woes

Maven Documentation generation woes 

For a while I have used APT (Almost Plain Text) for documenting a lot of my Java projects that use Maven.  There are good reasons behind this but at times the wheels do start to fall off a little.  They did while I was trying putting together (and still am) my notes on developing a web app with Apache projects Click and Cayenne.  I write the doco alongside the code and was always aiming to have Maven generate it so I could send it up as a blog.  Well it is easy enough to change the default Maven site layout when generating your doco, as I will describe below.  But the problem was I could not with the Google based blog tools upload the HTML and the images without editing it again on the blog site (pointing the image locations in the HTML).  So I thought, ok I'll upload/import the RTF or some other Maven/Doxia generated output to Google docs (which can then be sent to this blog).  The RTF output does require a lot more work and is IMO clunky, needing work for sure.  Such a good start to a product but still lacking momentum.  So anyway I will quickly show how I did the above 2 differtn things.

Change your site layout

Download the Velocity template default-site.vm and copy it to your Maven documentation project under src/site/site.vm.  If you know a thing or 2 about Velocity it will be easy to change this to your needs.

To include this in the "mvn site" run add this to your pom.xml:

            <plugin>

                <artifactId>maven-site-plugin</artifactId>

                <configuration>

                    <locales>en</locales>

                    <templateDirectory>src/site</templateDirectory>

                    <template>site.vm</template>

                </configuration>

            </plugin>

Then run "mvn clean site" and the changes made to the site.vm will be picked up.  I used this as a simple way to remove the nav and header panel and just create a single page.

Generate PDF/RTF etc

To do this the solution is right now not right OOB.  You can generate pdf by using "mvn pdf:pdf" and get a pretty nice result.  But if you want some other outputs then you have to use the Doxia plugin.  All these output are sourced from your APT and FML etc from the doco for your project.

The one challenge again is to do with images.  If you see an error such as "could not find URL"

Edit your pom.xml for the following.

Copy the src images to the target before the target is run:

        <plugin>

                <groupId>org.apache.maven.plugins</groupId>

                <artifactId>maven-antrun-plugin</artifactId>

                <executions>

                    <execution>

                        <id>book</id>

                        <phase>pre-site</phase>

                        <configuration>

                            <tasks>

                                <copy todir="${project.build.directory}/generated-site/pdf/book">  <!-- the book folder must be the same name as the ID tag of the book in the src/book.xml defined in the doxia-maven plugin below -->

                                    <fileset dir="${basedir}/src/site/resources/"/>

                                </copy>

                                <copy todir="${project.build.directory}/generated-site/rtf/book">

                                    <fileset dir="${basedir}/src/site/resources/"/>

                                </copy>

                            </tasks>

                        </configuration>

                        <goals>

                            <goal>run</goal>

                        </goals>

                    </execution>

                </executions>

            </plugin>

Run the doxia plugin when the site phase is run:

  <plugin>

                <groupId>org.apache.maven.doxia</groupId>

                <artifactId>doxia-maven-plugin</artifactId>

                <version>1.1.2</version>

                <executions>

                    <execution>

                        <phase>site</phase>

                        <goals>

                            <goal>render-books</goal>

                        </goals>

                    </execution>

                </executions>

                <configuration>

                    <books>

                        <book>

                            <directory>src/site/apt</directory>

                            <descriptor>src/book.xml</descriptor>

                            <formats>

                                <!--format>

                                  <id>latex</id>

                                </format>

                                <format>

                                  <id>xdoc</id>

                                </format>

                                <format>

                                  <id>pdf</id>

                                </format-->

                                <format>

                                    <id>rtf</id>

                                </format>

                            </formats>

                        </book>

                    </books>

                </configuration>

            </plugin>

The "book.xml" defines the structure of the output doc:

<book xmlns="http://maven.apache.org/BOOK/1.0.0"

      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

      xsi:schemaLocation="http://maven.apache.org/BOOK/1.0.0 ../../../doxia/doxia-book/target/generated-site/xsd/book-1.0.0.xsd">

    <id>book</id>

    <title>Click Cayenne Recipies</title>

    <chapters>

        <chapter>

            <id>intro</id>

            <title>Intro</title>

            <sections>

                <section>

                    <id>intro</id>

                </section>

            </sections>

        </chapter>