Q: How can I render the DocBook, Doxygen, and JavaDoc documentation in the Juggler source tree?

With all the Juggler documentation coming with the source code, I am wondering how to render it to HTML or PDF formats so that I can read it. How do I go about doing this?

A: Use the DocBook XSL Stylesheets, an XSLT processor, Doxygen, and JavaDoc.

Since 2002, the Juggler documentation has been integrated into the source tree. Of course, the API documentation has always been available in the source code itself, but now the user's guides are included with the source as DocBook documents. The full list of documentation that can be rendered is as follows:

  • DocBook-based guides (VR Juggler Programmer's Guide, Gadgeteer Device Driver Authoring Guide, etc.)
  • Doxygen-bsaed C++ API documentation
  • !JavaDoc-based Java API documentation

To render all the documentation, you will need the following:

At the bottom of the Team Guide page describing the use of DocBook for writing Juggler documentation, you will find archives containing the DocBook XSL stylesheets and the necessary Java-based rendering tools for rendering the DocBook-based documentation. All three archives contain the same information; they are simply compressed using different software. For the remainder of this text, assume that the necessary DocBook tools have been unpacked into the directory $HOME/docbook.

With the rendering tools installed, go to the top-level directory of the Juggler source tree and enter the following (the part in bold text) at the command prompt: 

	% '''make -f Makefile.docs DOCBOOK_ROOT=$HOME/docbook'''
	% '''make -f Makefile.docs release'''

The first command renders all the documentation. The second command installs the documentation in the directory $HOME/vrj-docs.dist along with an index.html file that makes browsing the documentation easy.

NOTE: For the Java API documentation to render completely, a full build of the Juggler Java code must exist, and the environment variables $TWEEK_BASE_DIR and $JCCL_BASE_DIR must be set to point at that build. For example, if Juggler is compiled in the directory $HOME/juggler/build, then $TWEEK_BASE_DIR and $JCCL_BASE_DIR should both be set to $HOME/juggler/build/instlinks.

Back to: LiveFaq