Vineet Manohar's blog

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

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.

• Docbkx Maven plugin options

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:

• Download the schemas for docbook to get validation and auto-completion in your XML editor
• DocBook 5: The Definitive Guide (online HTML)

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

• Maven Docbkx Plugin at CodeHaus
• Official Docbook page

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