Building The Documentation Package

The HPS documentation is tightly coupled with the libraries that it describes. Thus, to build the documentation package, you must first build the required elements of our HPS libraries. Although the HPS libraries will be supported on a variety of platforms, the documentation package will be built on Windows because all our supported languages (C++, C# and Java) are all supported on Windows.

Required Module/Repositories

Before we can begin to build the documentation, we need to get the requisite pieces from source control. Currently, they reside in CVS and GIT. The required modules/repositiories are as follows:

Required Tools

To build the documentation, you must have the necessary tools installed your system. The following are the list of required tools:

Documentation Source files

To build our documentation files, we need source files. There are two types of source files:

Building Header Files

We use scripts to generate our header files. These scripts can be found in the scripts directory in the hps repository. For each language, there is a different process for generating the header files. For C++, we generate header files and place them in the include directory using the genheader script.

For the Core Graphics library, to generate the header file, we use information from hoops_3daf as well as hps. For Sprockets, we only need information for the hps repository.

For C#, there is no traditional concept of header files. Information about the classes and methods resides directly in the assembly. In this case, we use *.cs files as our header files. These files are generated using the gencsharp script.

The C# source file generation must occur after the C++ headers are generated. The generated C++ headers are used as the source file for the gencsharp script. The gencsharp uses Elsa and Doxygen to parse the C++ header file into intermediate xml files. Elsa parses the code while Doyxgen parses the comments. These intermediate xml files are then fed in Gulp which generated a set of C# files. These will be the source for our documentation as well as the final C# assembly.

Building Documentation Files

Now that we have all our source files, we can run the build_docs script. This python script iterates through a list of specified directories in the docs repository. As in building of the header files, order matters. The dependency is analogous to the dependency order when building the hps libraries themselves. For example, we generate documentation for Core Graphics before Sprockets. All other content such as tutorials and enhancements are generated after all modules are generated.

Within a given module, the order matters for documentation generation as well. We always begin with building the reference manual. Below is a list of directories and the order in which their documenation should be generated:

  1. ref_manual: the reference manual which will contain three directories: cpp (C++), cs (C#) and java.
  2. prog_guide: the programming manual.
  3. tech_overview: the technical overview.
  4. release notes: this is not a separate directory but lives in the home directory of the module

Dox_Source

Within each directory where documentation will be generated, there will be a dox_source directory. This directory contains the main file that instructs Doxygen on how to generate documentation files. When Doxygen is run with the config.dox as its input, instructions for doxygen. When the build_docs script encounters a dox_source directory, it will look for a config.dox file. The resulting generated documentation is placed in the parent directory instead of dox_source. In the final documentation package, the dox_source directory is removed.

Generating Reference Manuals

For reference manuals, the config.dox instructions provides the location of the input header files. The path is relative and assumes that docs were pulled from GIT into a location within hps such that the docs directory sits side by side with other directories at the root like internals, scripts, demo, etc... If you do not have the correct directory structure, no reference manual entries can be generated.

Note that we have reference manuals for all of our supported languages.

In addition to config.dox, the dox_source might contain an IndexConfig.dox file. This file should always be run against doxygen after config.dox is run. This generated documentation from IndexConfig.dox is usually additional or supplimentary index for the reference manual.

Generating Documentation from Content Files

Documentation whose sources are content files include programming guides, technical overviews, tutorials and release notes. Their content generation occurs in the much the same way. Like the reference manuals, each directory will have dox_source directory in it with a config.dox file for instructions. The input files in this case do not live in the hps repository but live side by side with the config.dox file. They are denoted by the .pre extention on their names.