Table of Contents
The documentation for the individual modules is maintained separately from the source code build. This is done primarily because writing code to DocBook and related software would take too much time and gain us very little. For the most part, the Juggler Project documentation is intended for posting on the website. As such, the build environment is much more controlled than one that is provided for (easy?) use by the general public. The documentation build is still configurable, but in a different, less automatic method than what is used to build the source tree. This chapter explains the rules of the documentation build and how to configure it for use outside the VRAC lab.
Any module with DocBook-based documentation can be added to the documentation build. As with the source code build, there are rules that must be followed. With this smaller, less complicated build system, there are fewer things to deal with.
Within this subsection, we present the full list of targets
that must be implemented for correct operation within the
documentation build. As a reference, refer to the file
juggler/Makefile.docs. This list, containing
all of two targets, is as follows:
This target builds the documentation. It is up to each makefile to determine how much is built. In general, the makefiles are set up to generate HTML, PDF, and PostScript. This output may come from DocBook XML source or from output generated by Doxygen. Other tools may be used, but these two are the favored generators at this time.
This installs the documentation built by the
'docs' target. By default, the
documentation installation uses
$HOME/public_html/jugglerweb as the base
prefix. This truly reflects the intended use of this build
system. (To redirect the installed output, simply change the
setting for $(webroot) in
juggler/Makefile.docs.)
Targets such as 'clean' and
'clobber' are needed as well, but those makefiles
that include docbook.mk get them for free. If a documentation
generating makefile is not using docbook.mk, it must make its own
'clean' and 'clobber'
targets.
The individual documentation building makefiles are expected
to behave when installing the generated documentation. That is, they
should install to a subdirectory of $(webroot)
that reflects the appropriate project. In many cases, the
installation hierarchy should also reflect the version of the
software against which the documentation was written.
Each makefile is responsible for creating its own installation hierarchy and for installing any related, external files. The documentation build offers some automation to help with this, but its abilities are limited. At this time, the documentation build can be directed to install the image files that come with the DocBook style sheets and any local images that the documentation needs.