Agile documentation with Eclipse, Maven, Hudson and Docbook

>> Tuesday, September 28, 2010

As a Java software designer and developer, I have fantastic tools at my disposal. Things like Eclipse, Maven, Hudson. These tools help me design, write, manage and deliver software artifacts. However, when it comes to producing and managing documentation, we generally go back to the stone-age and use office productivity (sic!) software that simply does not play well with the principles of structuring, formatting and delivering content.

I have always assumed that there existed a better way of producing and managing technical documentation. One that could take advantage of the existing (and robust) software development infrastructure namely source control, IDEs, build management, repository management, etc. Well, I decided to bite the bullet and get organized and I must say I am quite happy with the result. In fact, it was relatively painless to get things working. Essentially, I wanted an open-source solution that could leverage my favorite tools: Eclipse or one of its derivatives, an SCM such as CVS or SVN, Maven and Hudson.

Actually, what got me on the right track is looking at several projects that managed extensive and high quality documentation such as Spring or Maven. Their on-line documents are clearly produced with a Docbook based system. I won't get into a long description of Docbook, there is enough out there for any curious individual, but in a nutshell, Docbook is a mature (its been around for quite some time) and comprehensive XML grammar that can be used to produce technical documentation using XSLT. XSL transformations are freely available to transcode Docbook XML into various HTML and PDF formats. That is exactly what I needed and, as I found out, the solution simply works. What more can I ask?

So here is how I use this technology:

  1. I use the standard Eclipse XML editor (backed by the Docbook DTD) to edit my content. I get all the benefits of schema based editing and validation and in fact, the XML editor tells me what I can put where and if I misplaced or omitted anything (try getting the same from MS Word).
  2. I defined a simple Maven project to hold my document(s) and use the com.agilejava.docbkx:docbook-xml plugin to generate the formatted output I need. Through simple POM configurations I am able to use 3 or 4 Maven commands to do the following: format my document, publish it and generate zipped artifacts containing the source and the transformed (formatted) output.
  3. I can release document versions and deposit them in a repository for safekeeping
  4. Since my Eclipse project is under source control and since I have access to a Hudson continuous integration server, whenever I check-in my source, Hudson triggers a Maven  job that generates and publishes the new version to a filesystem so it is available to my user community through HTTP or otherwise.
For those who want details on how it's done, the POM content for a simple project is included below.

Special thanks  to Vineet Monahar. His article on Docbook and Maven was very helpful.



 <?xml version="1.0" encoding="utf-8"?>  
   
 <project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"  
     xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">  
     <modelVersion>4.0.0</modelVersion>  
     <groupId>ca.qc.hydro.cej</groupId>  
     <artifactId>cej-guide-developpeur</artifactId>  
     <packaging>pom</packaging>  
     <version>0.0.1-SNAPSHOT</version>  
   
     <!--  
         Usage:   
           
         // Generate docbooks   
         mvn   
           
         // Generate and publish:   
         mvn clean process-resources -Dpublish  
     -->  
   
     <properties>  
         <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>      
     </properties>  
   
     <build>  
         <defaultGoal>process-resources</defaultGoal>  
         <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>  
   
                 <configuration>  
                     <highlightSource>1</highlightSource>  
                     <htmlStylesheet>css/stylesheet.css</htmlStylesheet>  
                 </configuration>  
                 <executions>  
                     <execution>  
                         <id>html</id>  
                         <phase>process-resources</phase>  
                         <goals>  
                             <goal>generate-html</goal>  
                         </goals>  
                         <configuration>  
                             <!-- This copies content (images, etc) for the HTML version -->  
                             <preProcess>  
                                 <copy todir="target/docbkx/html/images">  
                                     <fileset dir="src/docbkx/images" />  
                                 </copy>  
   
                                 <copy todir="target/docbkx/html/css">  
                                     <fileset dir="src/docbkx/css" />  
                                 </copy>  
                             </preProcess>  
                             <!-- Any parameters specific to HTML version go here -->  
                         </configuration>  
                     </execution>  
                     <execution>  
                         <id>eclipse</id>  
   
                         <phase>process-resources</phase>  
                         <goals>  
                             <goal>generate-eclipse</goal>  
                         </goals>  
                         <configuration>  
                             <!-- This copies content (images, etc) for the HTML version -->  
                             <preProcess>  
                                 <copy todir="target/docbkx/eclipse/images">  
                                     <fileset dir="src/docbkx/images" />  
                                 </copy>  
                                 <copy todir="target/docbkx/eclipse/css">  
                                     <fileset dir="src/docbkx/css" />  
                                 </copy>                                  
                             </preProcess>  
                             <!-- Any parameters specific to ECLIPSE version go here -->  
   
                         </configuration>  
                     </execution>  
   
                 </executions>  
             </plugin>  
   
            <plugin>  
             <artifactId>maven-assembly-plugin</artifactId>  
             <configuration>  
              <descriptors>  
               <descriptor>src/assembly/src.xml</descriptor>  
   
               <descriptor>src/assembly/transcoded.xml</descriptor>  
              </descriptors>  
             </configuration>  
            </plugin>      
               
         </plugins>  
   
     </build>  
   
     <profiles>  
         <profile>  
   
             <id>publish</id>  
             <activation>  
                 <property>  
                     <name>publish</name>  
                 </property>  
             </activation>  
             <build>  
                 <defaultGoal>process-resources</defaultGoal>  
   
                 <plugins>  
                     <plugin>  
                         <artifactId>maven-antrun-plugin</artifactId>  
                         <executions>  
                             <execution>  
                                 <phase>process-resources</phase>  
                                 <configuration>  
                                     <tasks>  
                                         <copy todir="\\SOME_NETWORK_FOLDER\eBooks\${project.artifactId}">  
                                             <fileset dir="target/docbkx">  
                                             </fileset>  
                                         </copy>  
                                     </tasks>  
                                 </configuration>  
                                 <goals>  
                                     <goal>run</goal>  
                                 </goals>  
                             </execution>  
                         </executions>  
                     </plugin>  
                 </plugins>  
             </build>  
         </profile>  
     </profiles>  
   
 </project>  

Read more...

  © Blogger template Webnolia by Ourblogtemplates.com 2009

Back to TOP