Creating documentation with maven

Question

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 article/book, and my desired artifact would probably be a PDF.

Answer 1

I recently implemented the project documentation for my maven multi-module project using docbook and the docbkx plugin for maven. I now have it automatically generating html and pdf files every time I build the project site. I think docbkx really rocks, so I would suggest you use that.

Its true -you can create a very nice site just using the maven site and doxia plugins. In fact I'm using those two to generate my project site, But doxia support for docbook is very limited and doesn't let you modularize documentation, including parts of documents in a main document, for instance. So for the big reference-manuals I'm using docbkx.

If you want to take a peek, my project is here. You can actually download the source and see the nitty gritty of it. And, of course, if you have any question regarding this setup, i'll be more than glad to help.

Cheers Carlos

Answer 2

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 3

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

Answer 6

Although the question is quite old I want to give an update on this. If you want to use LaTeX for your documentation you should use a maven plugin to generate the documentation. There are a couple of maven-plugins doing this but a lot of them are not maintained anymore. There is a new maven-plugin which requires none or less configuration to get it working and the generated PDF (or PS or DVI) can be published as artifact.

Have a look at: mathan-latex-maven-plugin

Answer 7

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>