Most enhancements to Hackystat are made via its "extension points": special constructs (often implemented in the core subsystem modules) that simplify the addition of certain "classes" of functionality. The "Sensor" and "Sensor Data Type" extension points are so important in Hackystat that they are organized into their own subsystems, but Hackystat contains many other extension points. (For details on extension points, see Chapter 24, Extension Point Definition Files.)
If you take a look at the Reference Guide, you'll see that the documentation for each specific extension point instance (such as the "DevEvent SDT" or the "Eclipse sensor") is presented as a section in a chapter devoted to that type of extension point. Thus, if you are defining an enhancement to Hackystat such as a Sensor Data Type, a Sensor, or any other extension point, your documentation will take the form of a Reference Guide Section. This purpose of this section is to show you how to set up this kind of documentation.
The easiest way to explain how to add a new Reference Guide section is to work through an example. Conveniently, the example Sensor Data Type module package called "hackyDoc_SimpleSdt.zip" used in Chapter 15, Designing sensor data types provides an excellent example of this kind of documentation. This package defines a new sensor data type called "SimpleSdt", along with the documentation files that enable a new section on this SDT to appear in the Reference Guide. If you are defining some other kind of extension point instance, such as a Sensor, the process is almost exactly the same as the following, and we will note the differences as we go along.
The first step is to download the hackyDoc_SimpleSdt.zip file, unzip it, and install it into your local configuration. Section Section 15.3, “Anatomy of SimpleSdt: Overview and Installation” provides more details on this process.
Once you have installed the hackyDoc_SimpleSdt module into your local configuration, you should check to make sure the documentation can be generated correctly by running "ant hackyCore_Build.buildDocBook". After executing that command, you should be able to view in a browser the file hackyCore_Build/build/war/docbook/index.html. Figure 18.1, “ The table of contents showing the SimpleSdt documentation section ” illustrates the Reference Guide with the installed SimpleSdt documentation.
As you can see, Section 13.13 contains the documentation for the SimpleSdt sensor data type provided by this module. Let's now explore how the hackyDoc_SimpleSdt module provided the information needed to produce this documentation section.
For the Hackystat build system to find the files you wish to be included as documentation, you must provide them in a directory called "docbook". The build system does not care where in your module you locate this directory, but you should make sure that you provide your documentation files inside a directory called "docbook", and you should generally avoid putting non-documentation files into that directory.
In the case of extension point documentation, the docbook directory is typically located in the directory where the other components of the extension point are provided. Example 18.4, “Location of the docbook/ directory in hackyDoc_SimpleSdt” illustrates one such docbook directory location.
Example 18.4. Location of the docbook/ directory in hackyDoc_SimpleSdt
hackyDoc_SimpleSdt/
src/
org/hackystat/doc/simplesdt/sdt/
docbook/
hackyDoc_SimpleSdt.simplesdt.sdt.docbook.def.xml
hackyDoc_SimpleSdt.simplesdt.sdt.docbook.xml
As you can see, the extension point (i.e. the SimpleSdt SDT) is defined in the module's "src/" directory, inside the subdirectory "org/hackystat/doc/simplesdt/sdt". Inside this directory (but not shown in this example) is the implementation of the sensor data type, as well as the "docbook" directory containing the documentation files.
In the case of the SimpleSdt sensor data type, only two files are required to document this extension point, a "docbook.def.xml" file containing a definition for this documentation, and a "docbook.xml" file containing the actual documentation.
![[Note]](gfx/admonitions/note.gif) | Why the l--o--n--g file names? |
|---|---|
At this point, you might be muttering to yourself, "Why are the names of these documentation files so ridiculously long? What is wrong with these people, anyway? Why couldn't they just name the file "simplesdt.xml"? In response, let me begin by confessing that I don't like typing long file names any more than anyone else does. There are two basic reasons why the documentation file names tend to be so long. First, all documentation source files must end with "docbook.xml" or "docbook.def.xml" so that the build system can distinguish documentation definition files from source files, and either of these files from the many other kinds of XML files in Hackystat. Second, and this is the critical reason, all of the documentation files are copied into the same directory during the build process. This means that if two documentation files defined in separate modules happen to end up with the same name, one of them will be overwritten during the build process and not appear in the generated documentation. For this reason, the public Hackystat modules all obey a naming convention for documentation files that guarantees that no two documentation files from different parts of the system will accidentally have the same name. The convention is that the documentation file starts with the hackystat module name, followed by the name of the instance being documented, followed by the extension point type (if present), and ends with either "docbook.xml" or "docbook.def.xml". Thus, for example, the SDT "SimpleSdt" in the module "hackyDoc_SimpleSdt" produces the source file "hackyDoc_SimpleSdt.simplesdt.sdt.docbook.xml". | |
As noted previously, part of the build system's responsibility is to construct a top-level index.docbook.xml file that indicates the set of files to be included in the documentation for this configuration, and the order in which they will appear. To do this, the build system uses the information in the documentation "definition" files, all of whose names end with ".docbook.def.xml". Example 18.5, “hackyDoc_SimpleSdt.simplesdt.sdt.docbook.def.xml” illustrates the docbook definition file for the SimpleSdt documentation.
Example 18.5. hackyDoc_SimpleSdt.simplesdt.sdt.docbook.def.xml
<hackydocbook>
<reference-guide-section chapter="Sensor Data Types"
sortString="SimpleSdt"
fileName="hackyDoc_SimpleSdt.simplesdt.sdt.docbook.xml" />
</hackydocbook>
As with all of the docbook definition files, the top-level tag is <hackydocbook>. In the case of Reference Guide section definitions, the tag inside the top-level tag is <reference-guide-section>, which supports exactly three attributes.
The first attribute, "chapter", takes a string that names the Chapter in which this documentation section will appear. The Hackystat build system has no a priori notion of what Chapters should appear in the Reference Guide: it dynamically determines the names of the chapters by processing the values associated with this chapter attribute. It is up to the writers of Reference Guide sections to use the same chapter string in order to ensure that their sections are collected together correctly.
The second attribute, "sortString", is a string that is used by the build system to alphabetically order the sections within a chapter.
The third attribute, "fileName", is a string that names the file containing the contents of this reference guide section.
Having shown where the docbook directory should be located, and how to define a documentation file, we can finally present the documentation itself. Example 18.6, “hackyDoc_SimpleSdt.simplesdt.sdt.docbook.xml” illustrates the docbook.xml file for the SimpleSdt documentation.
Example 18.6. hackyDoc_SimpleSdt.simplesdt.sdt.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_SimpleSdt:sec:sdt.simplesdt">
<title>The SimpleSdt Sensor Data Type</title>
<section>
<title>Overview</title>
<para>
The SimpleSdt sensor data type is designed to help new Hackystat developers become comfortable
with the design and implementation of sensor data types. This docbook file provides a template
for how the SDT documentation should be written.
<xref linkend="hackyDoc_SimpleSdt.sdt.attributes"/> documents the SimpleSdt attributes.
<table id="hackyDoc_SimpleSdt.sdt.attributes" frame="all" rowsep="1" colsep="1">
<title>SimpleSdt SDT attributes</title>
<tgroup cols="2" align="left">
<thead>
<row>
<entry>Attribute</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry>tstamp</entry>
<entry>The UTC time at which this data was collected.</entry>
</row>
<row>
<entry>tool</entry>
<entry>A string indicating the tool that collected this data, such as "BCML" or "LOCC".</entry>
</row>
<row>
<entry>name</entry>
<entry>A string indicating a name to be associated with this SimpleSdt sensor data instance. </entry>
</row>
<row>
<entry>elapsedTime</entry>
<entry>An Integer indicating elapsed time in seconds.
</entry>
</row>
</tbody>
</tgroup>
</table>
</para>
<para>
In addition to the above required fields for all Simplesdt
data, there are a number of "Common optional" attributes that can appear on
the property map. These are documented in <xref
linkend="hackyDoc_SimpleSdt.sdt.properties"/> so that sensor writers can
produce SimpleSdt sensor data that can be processed by the built-in
SimpleSdt analyses and reduction functions.
<table id="hackyDoc_SimpleSdt.sdt.properties" frame="all" rowsep="1" colsep="1">
<title>SimpleSdt SDT "Common Optional" properties</title>
<tgroup cols="2" align="left">
<thead>
<row>
<entry>Property</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry>url</entry>
<entry>Provides the home page associated with name.</entry>
</row>
<row>
<entry>units</entry>
<entry>Provides the units to be associated with elapsedTime, if not the default (seconds).</entry>
</row>
</tbody>
</tgroup>
</table>
</para>
</section>
<section>
<title>Applications of the SimpleSdt SDT</title>
<para>
This section provides a simple overview of how the sensor data is used, including examples of tools that would
generated this kind of data. See the existing Sensor Data Type documentation for examples.
</para>
</section>
</section>
Let's spend a moment to overview some of the features of this source file. Later sections of this chapter will detail the most common tags and conve ntions used in the Hackystat docbook representation.
All of the docbook.xml source files begin with a standard header, as shown next:
<?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;
]>
This is basically boilerplate code that defines the style of docbook used in the Hackystat documentation framework, and imports some standard URLs and definitions.
In the case of a Reference Guide documentation file, the top-level tag should be <section>. Here is how the SimpleSdt documentation begins:
<section id="hackyDoc_SimpleSdt:sec:sdt.simplesdt"> <title>The SimpleSdt Sensor Data Type</title> <section> <title>Overview</title> <para>
As you can see, we define a secion and provide it with a unique ID so that other areas of the documentation can refer to it via an <xref> tag. As with files, every ID in the docbook must be unique, and to help ensure that, you should always prefix your ID values with the module that the documentation is defined in.
In this case, we immediately define a subsection called "Overview" using a nested <section> tag. This subsection does not have an ID associated with it, since it is never referred to in other areas of the documentation.
Samples of code, tables, and images can be named with IDs and then referred to with an <xref> tag. The following documentation fragment illustrates this:
<xref linkend="hackyDoc_SimpleSdt.sdt.attributes"/> documents the SimpleSdt attributes. <table id="hackyDoc_SimpleSdt.sdt.attributes" frame="all" rowsep="1" colsep="1"> <title>SimpleSdt SDT attributes</title>
The "chapter" attribute value in your docbook definition file determines which chapter your Reference Guide section will appear in. However, there are no hard and fast rules for how to present information within a Reference Guide section, since the most appropriate structure and content will depend upon the extension point.
The best approach when writing a Reference Guide section is to start by reviewing the other Reference Guide sections that have already been written to see what structure and content is being followed. Then, write your section in a similar fashion.