Maven Docbook for beginners

Docbook is an XML format generally used for writing technical documentation. Many technical projects have documentation written in Docbook XML and checked in the source control system along with the source code. This makes it easy to ship documentation with the source and lets you keep versions of documentation in sync with the product version. This tutorial shows you how to write your first docbook documentation in a Maven project.

Write a simple docbook file

Create the following file:

src/docbkx/test.xml

A minimal docbook file

<?xml version="1.0" encoding="utf-8"?>
 <article xmlns="http://docbook.org/ns/docbook" version="5.0" xml:lang="en">
  <title>Hello, World</title>
  <para>My first documentation with Docbook</para>
 </article>

Generate html documentation

Configure pom.xml

The maven docbook plugin converts your docbook xml file to user friendly documentation in HTML. Add the following plugin declaration to your pom.xml

<build>
<plugins>
<plugin>
 <groupId>com.agilejava.docbkx</groupId>
 <artifactId>docbkx-maven-plugin</artifactId>
 <dependencies>
  <dependency>
   <groupId>org.docbook</groupId>
   <artifactId>docbook-xml</artifactId>
   <version>4.4</version>
   <scope>runtime</scope>
  </dependency>
 </dependencies>

 <executions>
  <execution>
   <phase>pre-site</phase>
   <goals>
    <goal>generate-html</goal>
   </goals>
  </execution>
 </executions>
</plugin>

Run the plugin

The above config runs the plugin in pre-site phase, and will automatically be called when you run mvn site. You can use the following command to manually run the plugin for purpose of testing:

mvn pre-site

This simple config scans the src/docbkx directory and produces the html documentation in target/docbkx/html directory. You should see the following output file:

target/docbkx/html/test.html

First docbook generated HTML

More plugin options

The plugin goal used above generate-html converts the docbook xml to html. There are advanced options to configure the CSS/XSLT used. Also, there are other goals available to generate documentation in more formats including pdf. Here’s the reference page for plugin documentation.

Learning Docbook format

Now that you are able to create a sample docbook and publish it, you might want to learn the Docbook format itself. Here are some links that should help you get started:

FAQ

  1. Are there other docbook plugins for Maven? Yes, there are a few other plugins. However, this one seems to be the easiest to use. See more info here.

References

http://opensource.bureau-cornavin.com/crash-course/en/index.htmlThis

Related posts:

  1. Tweet your builds with Maven Twitter Plugin
  2. JAXB code snippets for beginners
  3. Maven FAQ and code snippets for beginners
  4. How to automate project versioning and release with Maven
  5. How to auto-generate Maven plugin documentation

3 comments to Maven Docbook for beginners

  • faxe13

    Hi, I just wanted to let you know that there is a missing closing > in the tag of the pom.xml example which makes troubles with copy and past from the page into the pom.

  • vineet

    Fixed it. Thanks!

  • Ruchita

    Thanks a lot for creating this article. I was able to generate a maven site with docbook src file as instructed here. However, is there any way I can get back the css and velocity template customizations (along with the left hand navigation bar) with docbook output.
    Do I need to put all these resources under the docbook/template dir?

    Thanks,
    Ruchita

Leave a Reply

 

 

 

You can use these HTML tags

<a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>

Get Adobe Flash playerPlugin by wpburn.com wordpress themes