Using Docbook for your documentations

Docbook is a well-known tool for documentations which is commonly used by Open-Source projects. It consists in a XML grammar allowing describing the structure of your documentation (section, paragraph…). Tools are then provided (XSL stylesheets) in order to generate documentations in several formats such as HTML or PDF.
We won’t describe here how to create a docbook documentation but provides several hints in order to show how to create them. The following code describe a sample short extract of a docbook documentation:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
<book xmlns:xi="http://www.w3.org/2001/XInclude">
  <bookinfo>
    <title>Book title</title>
  </bookinfo>
  <part id="part-id">
    <title>Concepts</title>
    <partintro>
      <para>Part intro</para>
    </partintro>
    <chapter id="chapter-id">
      <title>Programming Easy Modelers</title>
      <sect1>
        <title>Section title</title>
        <para>A paragraph...</part>
      </sect1>
    </chapter>
  </part>
</book>

It’s now time to generate the documentation. Whereas the default stylesheets aren’t really suitable for a proper documentation render, some Open-Source projects patch them in order to provide more beautiful documentations. It’s the case of the Spring framework. The corresponding stylesheets are available in the Spring framework’s source code.
Moreover, Maven allows automating documentation generation with an extension for Docbook, the docbkx-maven-plugin plugin from com.agilejava.docbkx. The configuration of the plugin must be done in the pom.xml file of the module within the root project XML element as described below:
<build>
 <plugins>
   <plugin>
     <groupId>com.agilejava.docbkx</groupId>
     <artifactId>docbkx-maven-plugin</artifactId>
     <version>2.0.7</version>
     <executions>
       <execution>
         <id>single-page</id>
         <goals>
           <goal>generate-html</goal>
           <goal>generate-pdf</goal>
         </goals>
         <configuration>
           <chunkedOutput>false</chunkedOutput>
           <htmlCustomization>src/docbkx/resources/xsl/html.xsl</htmlCustomization>
           <foCustomization>src/docbkx/resources/xsl/fopdf.xsl</foCustomization>
           <postProcess>
             <copy todir="${basedir}/target/site/reference">
               <fileset dir="${basedir}/target/docbkx">
                 <include name="**/*.pdf" />
               </fileset>
             </copy>
             <copy todir="${basedir}/target/site/reference/html-single">
               <fileset dir="${basedir}/target/docbkx/html">
                 <include name="**/*.html" />
               </fileset>
             </copy>
             <copy todir="${basedir}/target/site/reference/html-single">
               <fileset dir="${basedir}/src/docbkx/resources">
                 <include name="**/*.css" />
                 <include name="**/*.png" />
                 <include name="**/*.gif" />
                 <include name="**/*.jpg" />
               </fileset>
             </copy>
             <move file="target/site/reference/pdf/index.pdf" tofile="target/site/reference/pdf/easymodelers-reference.pdf" failonerror="false" />
           </postProcess>
         </configuration>
         <phase>pre-site</phase>
       </execution>
       <execution>
         <id>multi-page</id>
         <goals>
           <goal>generate-html</goal>
         </goals>
         <configuration>
           <chunkedOutput>true</chunkedOutput>
           <htmlCustomization>src/docbkx/resources/xsl/html_chunk.xsl</htmlCustomization>
           <postProcess>
             <copy todir="${basedir}/target/site/reference">
               <fileset dir="${basedir}/target/docbkx">
                 <include name="**/*.html" />
               </fileset>
             </copy>
             <copy todir="${basedir}/target/site/reference/html">
               <fileset dir="${basedir}/src/docbkx/resources">
                 <include name="**/*.css" />
                 <include name="**/*.png" />
                 <include name="**/*.gif" />
                 <include name="**/*.jpg" />
               </fileset>
             </copy>
           </postProcess>
         </configuration>
         <phase>pre-site</phase>
       </execution>
      </executions>
      <dependencies>
        <dependency>
          <groupId>org.docbook</groupId>
          <artifactId>docbook-xml</artifactId>
          <version>4.4</version>
          <scope>runtime</scope>
        </dependency>
      </dependencies>
      <configuration>
        <includes>index.xml</includes>
        <htmlStylesheet>css/html.css</htmlStylesheet>
        <xincludeSupported>true</xincludeSupported>
        <sourceDirectory>${basedir}/src/docbkx</sourceDirectory>
        <!-- use extensions -->
        <useExtensions>1</useExtensions>
        <highlightSource>1</highlightSource>
        <highlightDefaultLanguage></highlightDefaultLanguage>
        <!-- callouts -->
        <calloutsExtension>1</calloutsExtension>
        <entities>
          <entity>
            <name>version</name>
            <value>${version}</value>
          </entity>
        </entities>
      </configuration>
    </plugin>
  </plugins>            
</build>

<pluginRepositories>
  <pluginRepository>
  <id>agilejava</id>
  <url>http://agilejava.com/maven/</url&gt;
  </pluginRepository>
</pluginRepositories>

You simply then have to execute the mvn site command in order to generate your documentations.

This entry was posted in Docbook, Documentation. Bookmark the permalink.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s