To build the documentation for your current Hackystat configuration, you can simply invoke the "hackyCore_Build.buildDocBook" Ant target. Example 18.1, “Sample invocation of hackyCore_Build.buildDocBook” illustrates the invocation of this target on a sample configuration.
Example 18.1. Sample invocation of hackyCore_Build.buildDocBook
C:\svn\hackyCore_Build>ant hackyCore_Build.buildDocBook
Buildfile: build.xml
hackyCore_Build.docbook.check.required.properties:
hackyCore_Build.docbook.init:
[delete] Deleting directory C:\svn\hackyCore_Build\build\docbook
[mkdir] Created dir: C:\svn\hackyCore_Build\build\docbook\gather\def
[mkdir] Created dir: C:\svn\hackyCore_Build\build\docbook\gather\image
[mkdir] Created dir: C:\svn\hackyCore_Build\build\docbook\gather\chapter
[mkdir] Created dir: C:\svn\hackyCore_Build\build\docbook\assemble\xml
[mkdir] Created dir: C:\svn\hackyCore_Build\build\docbook\tmp
hackyCore_Build.copyDocbookFiles.hackyApp_BuildAnalysis:
hackyCore_Build.copyDocbookFiles.hackyApp_Cgqm:
:
hackyCore_Build.copyDocbookFiles.hackyCore_Build:
[copy] Copying 8 files to C:\svn\hackyCore_Build\build\docbook\gather\def
[copy] Copying 14 files to C:\svn\hackyCore_Build\build\docbook\gather\image
[copy] Copying 14 files to C:\svn\hackyCore_Build\build\docbook\gather\chapter
:
hackyCore_Build.copyDocbookFiles:
hackyCore_Build.docbook.assemble:
[copy] Copying 14 files to C:\svn\hackyCore_Build\build\docbook\assemble\xml
[copy] Copying 14 files to C:\svn\hackyCore_Build\build\docbook\assemble\png
[copy] Copying 2 files to C:\svn\hackyCore_Build\build\docbook\assemble\xml
hackyCore_Build.docbook.process.html.chunked:
:
docbook.consolidate:
[copy] Copying 18 files to C:\svn\hackyCore_Build\build\docbook\tmp
[style] Processing C:\svn\hackyCore_Build\build\docbook\tmp\index.docbook.xml to C:\svn\hackyCore_Build\build\docbook\tmp\docbook-ready-file.tmp
[style] Loading stylesheet C:\svn\hackyCore_Build\lib\styler\preprocess\preprocess.xsl
html.chunked:
[copy] Copying 1 file to C:\svn\hackyCore_Build\build\docbook\tmp
[style] Processing C:\svn\hackyCore_Build\build\docbook\tmp\docbook-ready-file.tmp to C:\svn\hackyCore_Build\build\war\docbook\docbook-ref-file.tmp
[style] Loading stylesheet C:\svn\hackyCore_Build\build\docbook\tmp\customized.chunked.xsl.tmp
[style] Writing C:\svn\hackyCore_Build\build\war\docbook/pt01.html for part(part:userguide)
[style] Writing C:\svn\hackyCore_Build\build\war\docbook/ch01s02.html for section(sec:hackyCore_Build.installation.build.tools)
:
[style] Writing C:\svn\hackyCore_Build\build\war\docbook/pt04.html for part(part:refguide)
[style] Writing C:\svn\hackyCore_Build\build\war\docbook/index.html for book
[delete] Deleting: C:\svn\hackyCore_Build\build\docbook\tmp\customized.chunked.xsl.tmp
hackyCore_Build.docbook.build.html.chunked:
hackyCore_Build.buildDocBook:
[echo] (13:38:15) Completed hackyCore_Build.buildDocbook
BUILD SUCCESSFUL
Total time: 20 seconds
Sending build result to Hackystat server... Done!
The documentation build process consists of several stages, which we will detail in the next few sections. Although the build process is automated, a general understanding of what the process entails is useful in order to diagnose and repair build failures.
In the first stage of documentation generation, a set of directories are created in the hackyCore_Build/build/docbook directory. These directories are populated with docbook files by invoking the (implicitly defined) "copyDocbookFiles" target associated with each module in the configuration. In general, these targets look inside each module for the occurrence of one or more subdirectories called "docbook", and copy the documentation files out of their modules and into the hackyCore_Build/build/docbook directory. Only the documentation files associated with the current configuration are copied into the hackyCore_Build/build/docbook directory.
Once the documentation files for this configuration are copied into the hackyCore_Build/build/docbook directory, the next step is to construct a top-level XML file that specifies the overall structure of the documentation. To accomplish this, every documentation file (*.docbook.xml) has associated with it a "definition file" (*.docbook.def.xml). The definition file provides "meta-data" about the associated documentation file. Example 18.2, “Example docbook.def.xml file” shows an example definition file.
Example 18.2. Example docbook.def.xml file
<hackydocbook>
<chapter guide="Developer"
fileName="hackyCore_Build.documentation.docbook.xml"
rank="1.9">
<author name="Philip Johnson" linkend="ch:hackyCore_Build.documentation"/>
</chapter>
</hackydocbook>
As you can see, this docbook definition file says that there is a chapter intended for the Developer Guide that is in the file named "hackyCore_Build.documentation.docbook.xml", and it's "rank" is 1.9, which will be used to determine which chapters come before it and which chapters come after it. The definition file also indicates the author(s) of the chapter.
The top-level index.docbook.xml file, which specifies the overall structure of the documentation, is automatically generated by a simple Java program that finds all of the *.docbook.def.xml files, reads in their contents, and produces the appropriate top-level structure. Example 18.3, “Example index.docbook.xml file” shows one such index.docbook.xml file.
Example 18.3. Example index.docbook.xml file
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//Dawid Weiss//DTD DocBook V3.1-Based Extension for XML and graphics inclusion//EN" "http://www.cs.put.poznan.pl/dweiss/dtd/dweiss-docbook-extensions.dtd" [
<!ENTITY % isopub SYSTEM "iso-pub.ent">
%isopub;
<!ENTITY % local SYSTEM "local-entities.ent">
%local;]>
<book>
<title>Hackystat Framework Documentation</title>
<bookinfo>
<authorgroup>
<author>
<firstname>Cedric</firstname>
<surname>Zhang</surname>
</author>
<author>
<firstname>Philip</firstname>
<surname>Johnson</surname>
</author>
<author>
<firstname>Takuya</firstname>
<surname>Yamashita</surname>
</author>
</authorgroup>
<copyright>
<year>2001-2006</year>
</copyright>
<releaseinfo>Version: 7.4.323 | Build time: March 23 2006 15:05:09</releaseinfo>
</bookinfo>
<part id="part:userguide" xreflabel="User Guide">
<title>Hackystat User Guide</title>
<include file="hackyCore_Build.userguide.partintro.docbook.xml" />
<include file="hackyCore_Kernel.guidedtour.docbook.xml" />
<include file="hackyCore_Kernel.sensorinstallation.docbook.xml" />
</part>
<part id="part:adminguide" xreflabel="Administrator Guide">
<title>Hackystat Administrator Guide</title>
<include file="hackyCore_Build.adminguide.partintro.docbook.xml" />
<include file="hackyCore_Build.installation.docbook.xml" />
</part>
<part id="part:devguide" xreflabel="Developer Guide">
<title>Hackystat Developer Guide</title>
<include file="hackyCore_Build.devguide.partintro.docbook.xml" />
<include file="hackyCore_Build.devquickstart.docbook.xml" />
<include file="hackyCore_Build.documentation.docbook.xml" />
</part>
<part id="part:refguide" xreflabel="Reference Guide">
<title>Hackystat Reference Guide</title>
<include file="hackyCore_Build.refguide.partintro.docbook.xml" />
<chapter id="ref:extensionpointdefinitionfiles">
<title>Extension Point Definition Files</title>
<include file="hackyCore_Build.overview.extensionpoint.docbook.xml" />
<include file="hackyCore_Build.build.extensionpoint.docbook.xml" />
<include file="hackyCore_Kernel.command.extensionpoint.docbook.xml" />
<include file="hackyCore_Kernel.sdt.extensionpoint.docbook.xml" />
</chapter>
<chapter id="ref:sensordatatypes">
<title>Sensor Data Types</title>
<include file="hackyCore_Build.overview.sensordatatypes.docbook.xml" />
<include file="hackySdt_Activity.activity.sdt.docbook.xml" />
<include file="hackySdt_ReviewIssue.reviewissue.sdt.docbook.xml" />
<include file="hackySdt_UnitTest.unittest.sdt.docbook.xml" />
</chapter>
<chapter id="ref:sensors">
<title>Sensors</title>
<include file="hackyCore_Build.overview.sensors.docbook.xml" />
<include file="hackySensor_Eclipse.eclipse.sensor.docbook.xml" />
<include file="hackySensor_Jupiter.jupiter.sensor.docbook.xml" />
</chapter>
<include file="hackyCore_Build.authors.docbook.xml" />
</part>
</book>
The index.docbook.xml file specifies a "book" consisting of four parts, where each part corresponds to one of the four Hackystat Guides. For the first three parts, each part consists of a set of file inclusions, where each file contains a chapter. For the final part, the Reference Guide, the structure is a bit different: the included files contain sections, not chapters, and the chapters are generated from the section definitions.
Once the index.docbook.xml file is generated, the final step is to produce the documentation in the appropriate format(s). The first step is to "expand" the index.docbook.xml file by replacing the "include" file tags by their actual contents. This produces a single large file, which is fed to the Docbook style transformation packages. Currently, the only transformation used in the Hackystat build system is one that produces a "chunked" HTML representation of the documentation. However, in future, we will include a PDF version.
This part of the Hackystat documentation generation system is based upon the Ant and DocBook Styler Suite by Dawid Weiss.
The output of the Docbook transformation is a large number of linked HTML files, one per top-level section of each chapter. These are written into the hackyCore_Build/build/war/docbook directory, which makes them available as part of the built configuration.
From an operational point of view, building the Hackystat documentation is quite simple: just invoke a single Ant target called "hackyCore_Build.buildDocBook". The purpose of this section was to provide a deeper understanding of what happens when that target is executed: that files must be copied out of their modules and into a common build directory, that special "definition" files are processed, and that from those definitions a top-level "index.docbook.xml" file is generated that specifies the overall structure of the documentation. This is provided to Ant facilities that invoke the DocBook transformations to produce the formatted documentation.