The final enhancement to the SimpleSensor module is to add in the files required to generate DocBook documentation for this sensor in the Sensors chapter of the Hackystat Reference Guide.
This section will discuss the specific files required for DocBook documentation of the SimpleSensor, but it will not go into detail on the overall process of writing documentation for Hackystat. We recommend that you consult Chapter 18, Writing documentation for detailed instructions on Hackystat DocBook documentation.
Figure 17.9, “ SimpleSensor documentation page ” illustrates a portion of the documentation page in the Hackystat Reference Guide for the Simple Sensor.
This screen image does not show the entire page, which consists of five sections that typically appear in all of the Hackystat sensor documentation pages. The Overview section introduces the sensor, states its purpose, and indicates the sensor data types used by the sensor. The Installation section indicates how to use HackyInstaller to download the sensor and how to integrate use of the sensor into your development environment. The Installation Verification section describes how to test whether the sensor is sending data correctly to the server. The Installation Troubleshooting section explains how to diagnose problems that might occur, and the Uninstallation section explains how to disable or uninstall the sensor.
Many of these sections are quite similar for different sensors, and so you are encouraged to look at other sensor documentation pages for guidance on how to write these sections.
The documentation for the SimpleSensor is contained in four files in a single "docbook" directory. The file structure is as follows:
hackyDoc_SimpleSensor/src/org/hackystat/doc/simplesensor/
docbook/
hackyDoc_SimpleSensor.simplesensor.sensor.docbook.def.xml
hackyDoc_SimpleSensor.simplesensor.sensor.docbook.xml
hackyDoc_SimpleSensor.simplesensor.listsensordata.png
hackyDoc_SimpleSensor.simplesensor.configwindow.png
As you can see, the docbook directory is located in the simplesensor directory. You can also see that the file names look ridiculously long, but there is a good reason for this. First, the DocBook files will all be copied into a single directory for processing during the build. Thus, all Hackystat DocBook files by convention start with the owning module's name--in this case, "hackyDoc_SimpleSensor". This ensures that files created in one module will not accidentally overwrite files created in another module by unintentional use of the same file name.
In addition to a common prefix, the Hackystat build system requires certain DocBook files to have a common suffix in order to support correct processing. For example, files ending with "docbook.def.xml" indicate a file that provides a definition of a DocBook chapter or section, and are treated in a special manner by the build system.
Example 17.23, “hackyDoc_SimpleSensor.simplesensor.docbook.def.xml” shows the contents of the Hackystat DocBook definition file for SimpleSensor.
Example 17.23. hackyDoc_SimpleSensor.simplesensor.docbook.def.xml
<hackydocbook>
<reference-guide-section chapter="Sensors"
sortString="SimpleSensor"
fileName="hackyDoc_SimpleSensor.simplesensor.sensor.docbook.xml">
<author name="Philip Johnson" linkend="hackyDoc_SimpleSensor.simplesensor"/>
</reference-guide-section>
</hackydocbook>
This file is used by the Hackystat build system to understand how to locate the compose together the various DocBook files in a Hackystat configuration. In this case, the XML indicates that the file hackyDoc_SimpleSensor.simplesensor.sensor.docbook.xml contains a section intended for the Reference Guide chapter called "Sensors". It also specifies the author and link to the ID associated with this section. For more details on this XML file, see Section 18.4.3, “The *.docbook.def.xml file”.
Example 17.24, “hackyDoc_SimpleSensor.simplesensor.docbook.xml” shows the contents of the Hackystat DocBook documentation file for SimpleSensor.
Example 17.24. hackyDoc_SimpleSensor.simplesensor.docbook.xml
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE section 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;
]>
<section id="hackyDoc_SimpleSensor.simplesensor">
<title>SimpleSensor</title>
<section>
<title>Overview</title>
<para>
The SimpleSensor sensor is a Java-based sensor that sends development
events to the Hackystat server using the DevEvent SDT, which is documented
in <xref linkend="sec:sdt.devevent"/>.
</para>
</section>
<section>
<title>Installation</title>
<section>
<title>Prerequisites</title>
<para>
The SimpleSensor sensor requires &JavaVersion;.
</para>
</section>
<section>
<title>Download HackyInstaller and set your Hackystat Host and User Key </title>
<para>
Follow the instructions in <xref linkend="ch:sensorinstallation"/> to set
your Hackystat host and user key.
</para>
</section>
<section>
<title>Configure and install the SimpleSensor sensor</title>
<para>
In the HackyInstaller main window, select the SimpleSensor sensor and press
"Configure Selected Sensor". <xref
linkend="figure:hackyDoc_SimpleSensor.simplesensor.configwindow"/> shows
what the configuration window should look like after the path to the
SimpleSensor's home directory is set, the sensor is enabled, and the
"Install" button has been pressed to install the sensor.
<pasteFigure id="hackyDoc_SimpleSensor.simplesensor.configwindow" src="hackyDoc_SimpleSensor.simplesensor.configwindow.png">
SimpleSensor installer configuration window
</pasteFigure>
</para>
<para>
This sensor supports the following properties and paths:
<itemizedlist>
<listitem>
<para>
Enable simple sensor: This property controls whether the sensor is
active or not. If not checked, the sensor will not collect or send data
even if installed.
</para>
</listitem>
<listitem>
<para>
SimpleSensor home directory: This path specifies the directory where the
SimpleSensor code will be stored. Please create this directory if
necessary.
</para>
</listitem>
</itemizedlist>
</para>
</section>
<section>
<title>Instrument your development process with the SimpleSensor</title>
<para>
You must invoke the SimpleSensor in order to send a DevEvent to the
Hackystat server. One way to do this is by using "java -jar" as
illustrated in <xref
linkend="hackyDoc_SimpleSensor.simplesensor.invocation"/>.
<example id="hackyDoc_SimpleSensor.simplesensor.invocation">
<title>SimpleSensor Invocation</title>
<programlisting>
java -jar sensor.simplesensor.jar Run
</programlisting>
</example>
This invocation will send a DevEvent with the type "Run" to the Hackystat server.
</para>
</section>
</section>
<section>
<title>Installation verification</title>
<section>
<title>List Sensor Data</title>
<para>
To verify that the SimpleSensor is working, send a DevEvent using it, then
login to your account on your Hackystat server, and use the "List Sensor
Data" command on the Extras page to verify that Build data for today's date
was received by the server, as illustrated in <xref
linkend="figure:hackyDoc_SimpleSensor.sensor.listsensordata"/>.
<pasteFigure id="hackyDoc_SimpleSensor.sensor.listsensordata" src="hackyDoc_SimpleSensor.simplesensor.listsensordata.png">
List Sensor Data with SimpleSensor data
</pasteFigure>
</para>
</section>
</section>
<section>
<title>Installation troubleshooting</title>
<section>
<title>Troubleshooting general client-server problems</title>
<para>
The first step in troubleshooting your sensor installation is to verify
that your Hackystat host and key settings are valid and that you can
contact the Hackystat server, as described in <xref
linkend="sec:sensorinstallation:hackyInstaller.hostkey.setup"/>
</para>
</section>
<section>
<title>Checking client-side logging</title>
<para>
The SimpleSensor sensor writes out a file called SimpleSensor.0.log to the
.hackystat/logs directory that can be useful in debugging your
installation. Under normal conditions, this file should look similar to
<xref linkend="hackyDoc_SimpleSensor.simplesensor.logfile"/>.
</para>
<example id="hackyDoc_SimpleSensor.simplesensor.logfile">
<title>SimpleSensor.0.log example</title>
<para>
<programlisting>
Hackystat Version: 7.7.123 (January 23 2007 04:51:37)
SensorShell started at: 02/13/2007 13:44:42
Type 'help' for a list of commands.
Host: http://hackystat.ics.hawaii.edu/ is available and key is valid.
Defined shell command: Dependency
Defined shell command: Issue
Defined shell command: CodeIssue
Defined shell command: Perf
Defined shell command: FileMetric
Defined shell command: SampleSdt
Defined shell command: ReviewIssue
Defined shell command: Activity
Defined shell command: Cli
Defined shell command: ReviewActivity
Defined shell command: Coverage
Defined shell command: DevEvent
Defined shell command: UnitTest
Defined shell command: BuffTrans
Defined shell command: Commit
Defined shell command: Build
#> AutoSend [10]
AutoSend OK (set to 10 minutes)
AutoSend enabled every 10 minutes.
Checking for offline data to recover.
No offline data found.
#> DevEvent [add, tool=SimpleSensor, type=Run, path=/Users/johnson/svn-csdl/hackyDoc_SimpleSensor/build]
DevEvent add OK (1 total)
#> send
Sending sensor data (02/13 13:44:43)
Ping: Ping OK (contacted server http://hackystat.ics.hawaii.edu/ with valid key.)
Dependency: Send OK (No entries to send.)
AutoSend: AutoSend OK ('send' command ignored)
Issue: Send OK (No entries to send.)
CodeIssue: Send OK (No entries to send.)
Perf: Send OK (No entries to send.)
FileMetric: Send OK (No entries to send.)
SampleSdt: Send OK (No entries to send.)
ReviewIssue: Send OK (No entries to send.)
Activity: Send OK (No entries to send.)
Cli: Send OK (No entries to send.)
ReviewActivity: Send OK (No entries to send.)
DevEvent: Send OK (1 entries)
Coverage: Send OK (No entries to send.)
Commit: Send OK (No entries to send.)
BuffTrans: Send OK (No entries to send.)
UnitTest: Send OK (No entries to send.)
Build: Send OK (No entries to send.)
</programlisting>
</para>
</example>
</section>
<section>
<title>Submit a trouble report</title>
<para>
If none of the above troubleshooting activities solves your problem, then
you should send an email to your Hackystat Administrator to request help.
Please include in your email the following information:
<itemizedlist>
<listitem><para>The output from 'java -version'.</para></listitem>
<listitem><para>The output from 'java -jar sensorshell.jar -verify'.</para></listitem>
<listitem><para>The contents of your sensor.properties file.</para></listitem>
<listitem><para>The contents of the simplesensor.0.log file.</para></listitem>
<listitem><para>A description of the problem you are having.</para></listitem>
</itemizedlist>
</para>
</section>
</section>
<section>
<title>Uninstallation</title>
<para>
To disable SimpleSensor data collection temporarily, invoke HackyInstaller,
bring up the SimpleSensor configuration window, uncheck the "Enable
SimpleSensor sensor" property, and apply the setting. To permanently
uninstall the SimpleSensor sensor, press the "Uninstall" button.
</para>
</section>
</section>
For details of the DocBook syntax and organization of this file, see Section 18.4.4, “The *.docbook.xml file”.
To integrate our documentation into the Hackystat build system, we must make a minor modification to the local.build.xml file. The hackyDoc_SimpleSensor.install.pre-sensorshell target must be updated to include a call to the makeUpdateWebAppContent macro. This macro takes responsibility for finding all of the DocBook files (i.e. any files found in a docbook/ directory in the Hackystat module associated with this local.build.xml file) and copying them to a build location where they can be processed along with all of the other DocBook files in the current configuration. Example 17.25, “hackyDoc_SimpleSensor.simplesensor.docbook.def.xml” shows the updated version of the hackyDoc_SimpleSensor.install.pre-sensorshell target, with the added line highlighted.
Example 17.25. hackyDoc_SimpleSensor.simplesensor.docbook.def.xml
<target name="hackyDoc_SimpleSensor.install.pre-sensorshell" if="hackyDoc_SimpleSensor.available"
description="Copy over docbook and installer files.">
<makeUpdateWebAppContent module.src.dir="${hackyDoc_SimpleSensor.src.dir}"/>
<hackyCore_Installer.installXmlDefinitions module.src.dir="${hackyDoc_SimpleSensor.src.dir}" />
</target>
Note that the makeUpdateWebAppContent requires the name of the module's src directory.
Once you have added the docbook directory and its associated files, as well as enhanced the pre-sensorshell target in the local.build.xml file with a call to makeUpdateWebAppContent, you are ready to generate the DocBook documentation. Since you have edited the local.build.xml file, you should invoke AutoConfig in order to make sure that the Hackystat build system is congruent with your changes:
c:\svn\hackyCore_Build>ant -f autoconfig.build.xml
Buildfile: autoconfig.build.xml
run:
[mkdir] Created dir: C:\svn\hackyCore_Build\build\autoconfig
[echo] [AutoConfig] Generated modules.build.xml and sample.hackystat.build.properties.
autoconfig.build.default:
BUILD SUCCESSFUL
Total time: 1 second
c:\svn\hackyCore_Build>
Next, you invoke "ant hackyCore_Build.buildDocBook". Since there is quite a bit of output from this command, some sections have been elided in the listing shown in Example 17.26, “Ant output”.
Example 17.26. Ant output
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_Experiment:
(output deleted)
hackyCore_Build.docbook.assemble:
[copy] Copying 83 files to C:\svn\hackyCore_Build\build\docbook\assemble\xml
[copy] Copying 176 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:
modules.detection:
check.expand.zips:
check.expand.docbook-distribution.zip:
expand.docbook-distribution.zip:
check.expand.website-distribution.zip:
expand.website-distribution.zip:
check.required-properties:
xsltprocessor:
displayXsltProcessorInfo:
prepare:
copyResources-build:
[copy] Copying 1 file to C:\svn\hackyCore_Build\build\docbook\tmp\css
[copy] Copying 24 files to C:\svn\hackyCore_Build\build\docbook\tmp\gfx\admonitions
[copy] Copying 176 files to C:\svn\hackyCore_Build\build\docbook\tmp\figures
copyResources-distribution:
[copy] Copying 176 files to C:\svn\hackyCore_Build\build\war\docbook\figures
create.styler.uri:
docbook.consolidate:
[copy] Copying 87 files to C:\svn\hackyCore_Build\build\docbook\tmp
[style] Warning: the task name <style> is deprecated. Use <xslt> instead.
[style] Processing C:\svn\hackyCore_Build\build\docbook\tmp\index.docbook.xml to C:\svn\hackyCore_Build\build\docbook\tmp\docbook-ready-fil
[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] Warning: the task name <style> is deprecated. Use <xslt> instead.
[style] Processing C:\svn\hackyCore_Build\build\docbook\tmp\docbook-ready-file.tmp to C:\svn\hackyCore_Build\build\war\docbook\docbook-ref-
[style] Loading stylesheet C:\svn\hackyCore_Build\build\docbook\tmp\customized.chunked.xsl.tmp
(output deleted)
hackyCore_Build.docbook.build.html.chunked:
hackyCore_Build.buildDocBook:
[echo] (15:12:25) Completed hackyCore_Build.buildDocbook
BUILD SUCCESSFUL
Total time: 1 minute 52 seconds
Sending build result to Hackystat server... Done!
c:\svn\hackyCore_Build>
Once the documentation has been built, you can check it by pointing your browser at hackyCore_Build/build/war/docbook/index.html.