How to Use docbkx-tools as Maven DocBook plugin

When it comes to documentation of open source projects, DocBook is the favorite choice among many developers. As you all know, DocBook provides a comprehensive XML schema to document your project, which you can transform to any format such as html, pdf, webhelp etc. Here, I'm going to show you how to integrate DocBook in to your Maven project via docbkx-tools. This docbkx-maven-plugin makes docbook integration to Apache Maven much easier.

Reference DocBook XSLs from your customization layer

Probably you are not planning to use DocBook standard stylesheets alone, but have a little more customization to it. For that, you have to create a new customization layer, and import the standard docbook.xsl stylesheet. 

It's a little tricky how it's done in this plugin. You should give a symbolic reference rather than an actual file location when importing the stylesheets. You should use <xsl:import href="urn:docbkx:stylesheet/docbook.xsl" /> to give the symbolic reference.

What "urn:docbkx:stylesheet" refers will depend on what customization (html, xhtml, etc.) you want to use. If you want to use xhtml/chunk.xsl customization, first specify it in your XSL by     <xsl:import href="urn:docbkx:stylesheet/chunk.xsl"/> and then, in your POM, specify the <xhtmlCustomization>. Further details are explained below.

Integrating dockbkx-tools to Maven projects

OK, now let's see how to integrate this nice Docbook plugin to your maven project.

• First, you have to add the docbook plugin to your parent POM file pom.xml. The docbook xml documentation should be on path trunk/src/docbkx.

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

As you can see, the plugin depends on the docbook-xml artifact. After adding this structure to your POM, you just have to customize it according to your needs.

• Then, you have to set the configurations in <configuration> tag. In that, you should menion the xsl customization file, if you have a customized docbook XSLs. Else, you can just use the generic XSLs provided by DocBook. At this point, the docbkx's version is 2.0.11 and it uses DocBook-XSL-NS 1.75.2  version. Mind that it's the namespace version, so make sure you make your customized version with NS too. Else, you may encounter errors which could be hard to track. For the customizations, for html, use <htmlCustomization> tag to mention the customizations. For PDF, it's <foCustomization>. and <xhtmlCustomization> for, obviously, xhtml. A sample is below. You may put configurations under <executions> too, if you wish.
• The new customization to the DocBook-XSL family, DocBook WebHelp, is not yet included on this version, but the people are working on it to make it available as soon as possible. I'm eagerly waiting for it, mainly because I contributed to it a lot; plus it's a nice customization which you can actually put in the web for your audience to see.

        <configuration>
            <foCustomization>src/docbkx/xsl/fo.xsl</foCustomization>
            <xhtmlCustomization>src/docbkx/xsl/xhtml.xsl</xhtmlCustomization>
        </configuration>                

• Now it's to set the 'executions' you need to run. Executions specify what goals you run, copy CSS/JavaScript files you might have etc. A sample execution code is given below.

        <executions>

            <execution>
                <id>userguide</id>
                <phase>pre-site</phase>
                <goals>
                    <goal>generate-xhtml</goal>
                </goals>
                <configuration>
                    <includes>userguide.xml</includes>
                    <targetDirectory>target/site/userguide</targetDirectory>
                    <chunkedOutput>true</chunkedOutput>
                    <xhtmlCustomization>src/docbkx/xsl/userguide.xsl</xhtmlCustomization>
                    <postProcess>
                        <copy todir="target/site/userguide/">
                            <fileset dir="src/docbkx/template">
                            </fileset>
                        </copy>
                    </postProcess>
                </configuration>
            </execution>
        </executions>  

What happens there? First, it specifies the phase 'pre-site', which tells to Maven that, this execution should be run first when invoking 'mvn site' command. 

• <goal> - is set to generate-xhtml which will generate a xhtml output. Other options are generate-html and generate-pdf.
• <includes> - This tag specifies which document should be processed. The path was trunk/src/docbkx/userguide.xml.
• <configuration> - Then it comes to the configuration part. Most of it are self understandable. As you can see I've set the XSL customization I wish to use there. You can put it anywhere, both worked fine for me. 
• <chunkedOutput> will generate set of html files rather than one BIG html file which are broken down based on the tags <chapter>, <section> etc. in your docbook xml file.
• I copied all the CSS/JavaScript/Images to target folder by using the <postProcess> tag. It's easier. The source files were at src/docbkx/template.

• You may write another <execution> to generate the PDF output. The whole code I used is given below.

        <build>
            <plugins>
                <plugin>
                    <groupId>com.agilejava.docbkx</groupId>
                    <artifactId>docbkx-maven-plugin</artifactId>
                    <version>2.0.11</version>
                    <dependencies>
                        <dependency>
                            <groupId>org.docbook</groupId>
                            <artifactId>docbook-xml</artifactId>
                            <version>4.4</version>
                            <scope>runtime</scope>
                        </dependency>
                    </dependencies>
                    <configuration>
                        <foCustomization>src/docbkx/xsl/fo.xsl</foCustomization>
                    </configuration>
                    <executions>
                        <execution>
                            <id>userguide</id>
                            <phase>pre-site</phase>
                            <goals>
                                <goal>generate-xhtml</goal>
                            </goals>
                            <configuration>
                                <includes>userguide.xml</includes>
                                <targetDirectory>target/site/userguide</targetDirectory>
                                <chunkedOutput>true</chunkedOutput>
                                <xhtmlCustomization>src/docbkx/xsl/userguide.xsl</xhtmlCustomization>
                                <postProcess>
                                    <copy todir="target/site/userguide/">
                                        <fileset dir="src/docbkx/template">
                                        </fileset>
                                    </copy>
                                </postProcess>
                            </configuration>
                        </execution>


                        <execution>
                            <id>userguide-pdf</id>
                            <goals>
                                <goal>generate-pdf</goal>
                            </goals>
                            <phase>compile</phase>
                            <configuration>
                                <includes>userguide.xml</includes>
                            </configuration>
                        </execution>
                    </executions>
                </plugin>
            </plugins>
        </build>

YBQQQSEANSZ5