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:
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
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:
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:
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:
- Download the schemas for docbook to get validation and auto-completion in your XML editor
- DocBook 5: The Definitive Guide (online HTML)
- 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.