Creating documentation with maven

Question

I will just visit maven. Our team had a bad experience when we last looked at it, as it was during the period when maven was rebuilt from 1.x to 2.x, so many of the dependencies we needed were not transferred to new repositories, however, I there is time to review now.

I'm interested in using maven and LaTeX or DocBook to create documentation, and I was wondering if anyone had any sharing experience, project / module structure, good plugins to use, etc.

Many thanks: -)

Edit:

To clarify, I wanted to write a technical article / book, and my desired artifact would probably be a PDF file.

Answer 1

I recently implemented project documentation for my multi-module maven project using the docbook and the docbkx plugin for maven. Now I automatically create html and pdf files every time I create a project site. I think docbkx is really swinging, so I suggest you use this.

Its true - you can create a very good site using only the maven site and doxia plugins. I actually use these two to create my project site. But doxia support for the docbook is very limited and, for example, does not allow you to modulate the documentation, including parts of the documents in the main document. So for great reference guides, I use docbkx.

If you want a peek, my project is here . You can download the source code and look at it. And of course, if you have any questions regarding this setting, I will be more than happy to help.

Cheers Carlos

Answer 2

DocBook is one of the many supported materials for Doxia, which is used to generate maven documents. See 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 (containing documentation) with Maven using the mvn site command (i.e. using the plugin site ).

This plugin creates technical reports (such as Javadoc, module test reports, code coverage ...), but can also be used to create a “real site”. You have more details on this in this page .

Basically, you write your page using APT (almost plain text that is easy enough to understand) or the XML-based Xdoc format.

2 years ago, I created a complete user guide for one application that I developed using the XDoc format and the Site Maven plugin. On a global scale, it was pretty easy to create!

I hope this helps you!

Answer 4

I successfully use the Maven Docbkx plugin. You should try try

Docbkx

Answer 5

You should definitely take a look at the Maven Docbkx Plugin . This probably fits your needs. Support for Doxia DocBook is -um-suboptimal. In fact, the last time I tried it, he created something new that, as far as I can tell, there was no DocBook.

The Maven Docbkx plugin to which I refer supports all the settings of the world (via plugin parameters or overrides XSLT, if you are in this) + it contains some mechanisms for integrating with Maven. (For example, processing instructions for including Maven pom properties in your documents.)

Note that the goal is to have a plugin that prevents you from manually assembling the processing chain yourself. Thus, this plugin will do the conversion to FO and convert it to PDF.

Answer 6

Although the question is quite old, I want to report this. If you want to use LaTeX for your documentation, you must use the maven plugin to create the documentation. There are a couple of maven plugins that do this, but many of them are no longer supported. There is a new maven plugin that does not require a single or less configuration to make it work, and the generated PDF (or PS or DVI) can be published as an artifact.

Take a look: mathan-latex-maven-plugin

Answer 7

There is no official or semi-official AFAIK plugin that will handle 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 life cycle, t .e. at the same time that the project website is built.

For example, 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>