Documentation of software libraries and APIs has a well deserved reputation for being incomplete and hard to use. Personally, I had a lot of difficulty making documentation for the Boost Serialization Library. The following opinions are the the result of this and other experience.
Libraries on this web site are required to include documentation in the for of HTML pages. This is the common denominator that permits the library documentation to be easily consulted on the web as well as locally. The library directory structure includes a directory labeled HTML for this purpose. The generation of these pages is left to the library author. There are various ways to do this.
One can just prepare the HTML pages with a simple text editor. In many cases this is the simplest to do and many libraries have been documented in this manner. The main disadvantage is that PDF (and maybe others) can't be prepared from the html pages. Also as the library gets larger, it becomes tedious to keep everything in sync.
Edit documentation files in XML format with a text editor. The XML should follow the rules prescribed for BoostBook
Generating of HTML/PDF files from the BoostBook XML depends upon the Boost Build system. This in turn entails (as far as I can tell) updating one's local copy of the $BOOST_ROOT/doc directory and then running Boost bjam.
The generated documentation will appear in the $BOOST_ROOT/doc/html directory.
There is lot's to like about BoostBook.
The DocBook/BoostBook concept of structuring content and de-coupling it from presentation is sound.
The system can produce documentation in HTML and in PDF as well as potentially other formats.
Presentation is attractive, consistent and unified across different rendering formats.
BootBook defines a large group of XML tags which can be used characterize elements in C++ documentation. These includes things like function name, const, etc. etc. Potentially these could be used to generate useful things like function cross references, syntax coloring and the like.
The documentation for BoostBook is pretty good. It is created as an extension to DocBook. As such, it leverages on the extensive documentation available for that system.
On the other hand, there's a lot to dislike as well:
Editing XML is a royal pain. In part its just the ugliness and verbosity. XML documents are edited according to a set of grammar rules specified in a DTD or Schema. As BoostBook is derived from DocBook, it inherits all the rules from DocBook, and adds more of it's own. These rules are enforced by the build system so the author has to get them right. This turns out to be quite an effort since the rules are quite detailed an elaborate.
Though BoostBook specifies a large collection of tags to characterize documentation elements, the large majority of these are not used by Boost library documentation It seems that that they've been included in the hopes of being available for future use. This would be OK except for the fact that the attaching all these tags to one's documentation would be a huge job - which would yield no benefit with the current document preparation system.
It's not clear from the BoostBook documentation which tags are used/useful and which should not be bothered with. This leaves one with questions about under what circumstances each tag should be used.
Building HTML/PDF files from BoostBook XML files requires threading your library into your local Boost directory hierarchy, learning about how to configure and run BoostBuild, using the HTML/PDF which is left somewhere else in the local Boost directory. That is, conversion of documents in intimately coupled with BoostBuild. I understand the appeal of this for those whose task it it to deploy Boost as a monolithic software package. And it may be OK for those whose docmentation is done and already checked into the Boost directory, But for the rest of us, its very unwieldy.
Doxygen is a system for generating documentation of class and function types by scanning the progrogram code along with from enhanced comments included by the author.
Clearly it's been influenced by Literate Programming concepts.. This looks like a good thing to me.
Doxygen works pretty much as advertised.
Using Doxygen to get a specific kind of output requires setting the right combination of configuration options (There are scores of these) and including special comments in the source code.
A lot of the Doxygen generated documentation I've seen seems just to do little more than paraphrase the code. After spending some time experimenting with it, I've come to believe that this is likely in large part due to the manner that Doxygen has been used. One might be able to generate the documentation I want, but it would require a lot of effort in tweaking the configuration and the program comments.
The principle disadvantage of BoostBook is that editing XML in accordance with BoostBook rules is very tedious. To address this issue, QuickBook was created. It has it own, much simpler, set of syntax rules for creating documentation. QuickBook files are created with any text editor. The output from QuickBook is XML which follows the BoostBook rules. This output is processed as would any BoostBook XML would be. QuickBook has been popular. Approximately 1/3 of the boost libraries use it. Of course that's another way of saying that 2/3 of the libraries don't use it. I sill has a few disadvantages:
It's not a WYSIWYG editor.
It's yet another "little language" to learn.
Like many "little languages" it's not that easy to extend if you want to do something that it doesn't already include. Adding a feature means understanding the source, modification and recompiling.
I didn't see a way to get what I really want - see below.
Here's my personal wishlist - in no particular order - for a documentation system for C++ libraries.
A system which separates content from presentation so the same files can be used to generate documentaion as web pages, PDF files, and perhaps other formats such as htmlhelp and ePub.
This requirment is fullfilled by using BoostBook with no changes. A small additional XSLT styling sheet is employed to interface with the rest of the system.
An easy to use WYSISWYG editor which
works in all environments.
shows the document structure.
gives a good idea what the final presentation will look like.
guarentees that docments respect structure requirements. For example, it should prohibit the creation of a table row anywhere but inside a table.
Includes facilities for specification of document elements such as program listings, tables, etc.
Permits the creation of "templates" of premade document fragments which can be inserted into the document and then modified. Basically I want to include the "template" for Type and then use it as a form to fill in the specific information for some type.
includes a spelling checker
This requirement is fullfilled is XMLMind - a free XML editor. This beatifully made product permits one to add his own XML syntax checking files (DTD files). I've added files to enforce the extra rules that BoostBook requires. I've also added some "templates" for C++ library documentation elements: library, concept, type, and function. So one can build his documentation from within the editor by adding in hte standard templates and "filling in the blanks". This will go a long way to making "C++ library formal documentation" with a minimum of effort. Others agree with this assessment.
A simple system for generating the various required documentation formats from the edited source.
I've addressed this by creating some custom XSLT stylesheets which extend the standard BoostBook ones. These just remove the requirement that the XML files be part of the standard Boost Source tree. Finally, I've set up a directory containing all the DocBook stuff so that I can create HTML documentation with a three line batch file. This has made my documentation system usable without using BoostBuild and without having to make a source tree which looks like boost. Finally, the generated pages use the same "look and feel" as the BoostBook generated pages.
Setup BoostBook and XSLT.
Make sure the Boost Libraries and Tools are installed.
Install xsltproc as described in Getting Started
Follow the procedure in Configuring xsltproc
Follow the procedure in Configuring local DocBook XSL and DTD distributions
You should now have a designated directory with the DocBook XSL and DTD distributions installed. Set the Shell/Bat variable
DOCBOOKto point to the directory.
catalog.xmlto this directory.
Read the comments in
catalog.xmland edit the file accordingly. This will result in references to local copies of BoostBook and DocBook tools on your local file system and permit the usage of XML processing tools without dependence on an internet connection.
Set the Shell/Bat variable XML_CATALOG_FILES to point to the above file:
Setup XMLMind with BoostBook configuration extension
Download and Install the free personal edition of XMLMind for your environment:
UnZip this file into the XMLMind program directory. This directory should look like:
<XMLMind program directory> addon/ config/ boostbook boostbook.css boostbook.dtd boostbook.xxe boostbookcatalog.xml template/ concept.xml function.xml library.xml metafunction.xml section.xml type.xml
Verify that XMLMind is properly configured by invoking File->New shows
At this point, one should be able to create BoostBook based documentation with the XMLMind editor.
Using XMLMind to edit BoostBook documentation:
Editing with XMLMind takes some getting used to. It does feel quite unwieldy at first.
To get the hang of it, practice editing the BoostBook documentation for a library you've already downloaded. Note the the safe_numerics demo library documentation has been prepared with this system so it would be a good candidate to practice with.
XMLMind is very well docmented and explained - including videos! - check though all this information.
Ideally one would be totally insulated from details of DocBook/BoostBook. Unfortunately, one still has to know something about these packages. Here is a list of links which contain useful information.
Any XML editor is at it's root a system for editing a very elaborate tree of nexted XML elements can be very, very tedious. For this reason, it's very helpful to use copy/paste of "branches" which are already complete. This speeds up the process considerably for things like tables, etc.
Lookup the "node selection bar" in the XMLMind help. This is key to understanding where you are in the the node tree.
Edit in WYSIWYG mode. This guarentees that your document follows that BoostBook Document Type Definition and that the BoostBook Tool chain will produce Boost conformant documentation.
Make your documentation as a "Modular Document". Use safe_numerics as an example and lookup the XMLMind help that shows how to do this.
Using all of the above, the process of making library documentation can be summarized as:
File->New and select library to create a new document. This will be a "skeleton" of the documentation for your library.
Each time you create a new concept, type, or function, invoke File->New and select the appropriate template. This will create a new document of the selected type and make it ready to edit.
Edit the contents of each created template and save it under it's unique file name.
Link each newly created document into the library document using the procedure described in the XMLMind help.
Delete any unneeded sections and Add any required new ones as appropriate.
Once library documentation has been created in BoostBook/DocBook format we can render it in a variety of formats. This is done with the BoostBook toolset. In the official Boost distribution, this is done with BoostBuild. We use a simpler more transparent method. Creating HTML documentation is a two step process using xslt.
Translate BoostBook XML to DocBook XML xsl stylesheets
Translate the resulting DocBook XML to HTML standard DocBook style sheets.
These command accomplish the above
xsltproc --nonet --xinclude bb2db.xsl safe_numerics.xml | xsltproc --nonet db2html.xsl -
In addition, we need to copy a few files from the boost installation. The following files should be copied to the html directory from the boost root directory.
doc/src/boostbook.css // cascaded style sheet
to give boost "look and feel"
doc/html/images // directory of images for
and finally you should add to the html directory a file named
pre-boost.jpg. After all this, the html documentation
director structure should look like the following
doc/ html/ boostbook.css index.html other html files .... images/ png files ... boostbook/ xml files containing boost book documentation makehtml.bat // batch file which creates html from boost bookxml makehtml.sh // batch file which creates html from boost book xml
The logo on your documentation can be changed either by replacing
pre-boost.jpg with your own or editing the
dbt2html.xsl to point to a different logo.