Greetings, all, and happy new year! I've just made a number of commits which conclude the basic implementation of the new documentation system. This is a really significant step forward for the usability of the system, because it means:
* The hackystat docbook documentation is now partitioned into three "parts" called the User, Developer, and Administrator guides. (Currently, I've only got the existing User guide converted to the new format.) * User, administrator, and developer documentation can now be uniformly represented in docbook, can contain cross-links to other chapters in the same or other guides, and can be packaged with each release of the system. * Hackystat documentation can now correspond to the specific set of modules included in a configuration. In other words, if a configuration does not include a certain module (say, hackyApp_Pri), then the user, developer, and administrator documentation for that module will not be included in that configuration. Thus, each server will have a 'custom' documentation set available from its home page with just the chapters appropriate to its configuration. * Each module can (and should) include documentation about itself, and this documentation can be divided into as many chapters as needed and partitioned among the User, Developer, and Administrator guides as appropriate. The implementation of the new approach required some additions to autoconfig--there are now a bunch of targets in modules.build.xml that 'gather' docbook documentation files from across the available modules. Then, there is a new DocbookConfig class that reads a set of special <module>.def.docbook.xml files that provide information about the set of chapters and which guide they belong in, as well as a 'ranking' number that determines how to order the chapters within a guide. This data is used to generate a file called index.docbook.xml containing the overall specification of the three part docbook. Finally, the docbook machinery is invoked in the normal way to build the actual guides. I have not yet cut over to the new system for use in the daily build; I want to do a bit more testing first. I also hope to convert the existing administrator (installation) guide from HTML into docbook XML in the next few days. Finally, I will write a chapter for the developers guide on how to write docbook documentation for this new system! Another chapter that needs to be written ASAP is, of course, a chapter on how to integrate new modules into the build. When we do the cut-over, we'll need to make some slight changes to hackydevsite. Basically, we'll want to copy over the generated docbook from the hackystat-ALL configuration to the hackydevsite area, so that we can provide links to all of the available docbook chapters for all public modules from the most recent nightly build of the system on the front page of http://www.hackystat.org/. I have to go to LA for a DARPA meeting on January 9, and with any luck I'd like to get all of this done before I leave! Cheers, Philip
