Creating documentation with maven

Question

Hi,

I'm just in the middle of revisiting maven. Our team had a bad experience when we last looked at this, as it was during the period when maven was rearchitecting from 1.x to 2.x, so a lot of the dependencies we needed hadn't been moved across to the new repositories. However, I have the time to reconsider now.

I am interested in using maven and either LaTeX or DocBook for creating documentation, and I was wondering if anyone had any experiences to share, project/module structure, good plugins to use, etc...

Many thanks :-)

Edit:

Just to clarify, I was looking to write a technical artcile/book, and my desired artifact would probably be a PDF.

Answer 1

You can easily create a site (that contains documentation) with Maven using the mvn site command (i.e. using the plugin site).

This plugin creates technical reports (such as Javadoc, Unit tests reports, code coverage...) but can be also used to create a "real site". You have more details about that in this page.

Basically, you write your page using APT (Almost Plain Text which is quite simple to understand), or a XML-based format, Xdoc.

2 years ago, I create a complete user guide for one application I developed, using the XDoc format and the Site Maven plugin. Globally, it was quite easy to create!

I hope this will help you!

Answer 2

There is AFAIK no official or semi-official plugin that will process LaTeX or DocBook, but what you could do (besides using the aforementioned site plugin) is to configure the exec plugin to process your LaTeX/DocBook sources during the site lifecycle, i.e. at the same time that the project's website is built.

E.g., something like

<plugin>
  <groupId>org.codehaus.mojo</groupId>
  <artifactId>exec-maven-plugin</artifactId>
  <executions>
    <execution>
    <id>latex</id>
    <goals>
      <goal>exec</goal>
    </goals>
    <phase>site</phase>
      <configuration>
          ...
      </configuration>
    </execution>
  </executions>
</plugin>

Answer 3

DocBook is one of the many supported inputs to Doxia, the engine used to generate docs by maven. Refer here: http://maven.apache.org/doxia/modules/index.html

In fact, the Doxia site answers your exact question: http://maven.apache.org/doxia/book/index.html

Answer 4

I've been using with success the Maven plugin Docbkx. You should give it a try

Docbkx

Answer 5

You should definitely take a look at the Maven Docbkx Plugin. It probably fits your needs. Doxia's support of DocBook is -uhm- suboptimal. In fact, last time I tried it, it generated something new that - as far as I could tell - wasn't DocBook.

The Maven Docbkx Plugin that I'm referring to supports all the customizations of the world (through plugin parameters, or XSLT overrides, if you're into that) + it features some mechanisms to integrate it with the Maven build. (Such as processing instructions for including Maven pom properties into your documents.)

Note that the ambition is to have a plugin that prevents you from having to manually put together a processing chain yourselves. So this plugin will both do the transformation to FO, and transforming that to PDF.