DoxyComment formatting template

(previously known as the doxyxsltproc project)

Content:
Getting the latest version
Introduction
Requirements and installation
Using the template
Formatting template features
How it works
Quirks

Getting the latest version

This package is being updated from time to time. Below you will find links to the available downloads:

View the change log
Download the DoxyComment formatting template

The DoxyComment formatting template is an xslt style sheet for xml files generated by Doxygen. The style sheet processes the xml output to generate xhtml compliant web pages similar in structure and design to Microsoft's MSDN library. The style sheet embeds (using xml data islands) mshelp2 compliant meta-data to support generation of table of contents and various indices.

The package also contains a test sample, which illustrates how the extraction and generation process can be automated using simple batch scripts.

Requirements and installation

Requirement	Description
Doxygen	Doxygen is used to extract and cross-link documentation from your source files. Doxygen outputs the documentation in an open xml format.
nxslt2	nxslt2 is used to process the xml output from Doxygen. The processor applies various page templates to selected sub-sets of the xml hierarchy to form the output documentation pages. Any xslt processor should work as long as it supports the exslt extensions (you will have to modify the build scripts though).
Microsoft Help 2.0 utilities	The Microsoft Help 2.0 utilities are used to compile and register mshelp2 collections. If you are using Microsoft Visual Studio 2005 you must download the Visual Studio 2005 SDK (v2 RTM) to get them. If you are still using Visual Studio .NET 2003 you can download the Visual Studio Help Integration Kit 2003. Both downloads are available from the Visual Studio 2005 Extensibility Center on MSDN (free, registration required). If you don't care about mshelp2 collections you don't need the utilities (you will have to modify the build scripts to skip compilation).
Windows Command Prompt	The test sample comes with a number of scripts to help you run the various steps of the extraction and build process. The scripts are written as standard batch scripts and require the Window Command Prompt to run. If you use an alternative operating system you will have to write your own scripts.

Installation

The template is distributed in a simple zip archive. Please download and extract to a location of your choice.

The sample build scripts rely on the directory structure defined in the zip archive (if you plan on using the scripts out-of-the-box you must preserve the folder structure). The scripts also assume the following tools to be available in your path:

doxygen.exe
nxslt2.exe

hxcomp.exe (Microsoft Help 2.0 Compiler), hxreg.exe (Microsoft Help 2.0 Help Registration Utility)

SDK version	Default installation path
Visual Studio Help Integration Kit 2003	`<program files>\Microsoft Help 2.0 SDK`
Visual Studio 2005 SDK (v2 RTM)	`<program files>\Visual Studio 2005 SDK\2006.04\VisualStudioIntegration\Archive\HelpIntegration`

dexplore.exe (Microsoft Help 2.0 Viewer)

SDK version	Default installation path
Visual Studio Help Integration Kit 2003	`<program files>\Common Files\Microsoft Shared\Help`
Visual Studio 2005 SDK (v2 RTM)	`<program files>\Common Files\Microsoft Shared\Help 8`

Using the template

Fig 1. DoxyComment formatting template data flow.

Overview

Fig 1. shows the basic build steps required to build documentation with the DoxyComment formatting template.

First step in the build process is to extract and link the documentation from the various source files. This build step is entirely handled by doxygen. Class library documentation is typically embedded (using doxygen compliant comment blocks) directly into C/C++ source files and further documentation supplied as simple text file documents (*.ddoc files in the sample project). Doxygen outputs extracted and linked documentation in an open xml format.

Next step in the build process is to apply the DoxyComment formatting template to the extracted xml documentation. The DoxyComment formatting template defines how the source data is processed into xhtml pages and mshelp2 compliant meta-data. This build step is done using the nxslt2 tool (xslt source code for the template can be found in the template sub- directory of the installation folder).

The last (optional) part of the build process is to compile the generated documentation into a deployable format (archive). This build step is handled by the Microsoft Help compiler.

The test project

As an introduction to using the formatting template I have created a small sample project. The project can be found in the test sub- directory of the installation folder.

The test project has the following files and directories:

reg

The reg folder contains the collection level registration files. These files are used for registration in the help system (see the reg_help.cmd script).
script

The script folder contains a number of scripts to help you automate the build process for the documentation.
src

The src folder contains the source code for the sample project. Class documentation is embedded in the C/C++ source files (*.cpp,*.h). The doc sub-folder contains the source code for documentation pages (*.ddoc). Comment blocks and documentation pages adhere to Doxygen's documentation standard.
test.doxygen

The Doxygen project file defines which files to include in the documentation extraction and linking process.
test.xml

The project file is used by the formatting template. File contains various information needed by the template during the documentation build process.
test.hxc, test.hxf, test_alinks.hxk, test_klinks.hxk test_named_url.hxk

Project level mshelp2 files used generate the test_prj collection. The build process is started using the build_help.cmd script.

The build scripts

Important: Make sure your path is set up correctly before running any of the build and registration scripts (see the Requirements and installation section).

Script Description

Script	Description
`build_help.cmd <configuration>`	Script extracts xml documentation from the sources files using Doxygen and builds the xhtml documentation pages using nxslt2 and the formatting template. The script also invokes the Microsoft Help 2.0 compiler to generate the test_prj collection. Configurations: `public` Builds the public version of the documentation. `internal` Builds the internal version of the documentation. Intermediate and output files are placed in a sub- directory called `test_`configuration`_build`.
`reg_help.cmd <command>`	Script installs or uninstalls the test_prj collection in the DoxyComment namespace using the `hxreg.exe` utility. Commands: `install <configuration>` Installs the test_prj collection in the DoxyComment namespace. Configurations: `public` Installs the public configuration of the test_prj collection. `internal` Installs the internal configuration of the test_prj collection. `uninstall` Uninstalls the current configuration of test_prj collection and the DoxyComment namespace.
`view_help.cmd [option]`	Script starts the Microsoft Document Explorer (`dexplore.exe`) to view the DoxyComment namespace. Options: `vshik2003` Must be specified if your are using the Visual Studio Help Integration Kit 2003. Note: If you don't specify the `vshik2003` option the script will assume you are using the Visual Studio 2005 SDK.

build_help.cmd <configuration>

Script extracts xml documentation from the sources files using Doxygen and builds the xhtml documentation pages using nxslt2 and the formatting template. The script also invokes the Microsoft Help 2.0 compiler to generate the test_prj collection.

Configurations:

public: Builds the public version of the documentation.
internal: Builds the internal version of the documentation.

Intermediate and output files are placed in a sub- directory called test_configuration_build.

reg_help.cmd <command>

Script installs or uninstalls the test_prj collection in the DoxyComment namespace using the hxreg.exe utility.

Commands:

install <configuration>

Installs the test_prj collection in the DoxyComment namespace.

Configurations:

public: Installs the public configuration of the test_prj collection.
internal: Installs the internal configuration of the test_prj collection.

uninstall

Uninstalls the current configuration of test_prj collection and the DoxyComment namespace.

view_help.cmd [option]

Script starts the Microsoft Document Explorer (dexplore.exe) to view the DoxyComment namespace.

Options:

vshik2003: Must be specified if your are using the Visual Studio Help Integration Kit 2003.

Note: If you don't specify the vshik2003 option the script will assume you are using the Visual Studio 2005 SDK.

Formatting template features

Feature	Description
[More to come.]	[More to come.]

How it works

[More to come.]

Quirks

[More to come.]

$Id: template.html 55 2006-09-17 09:35:14Z tgram $
Copyright © 2006 by Troels Gram.