9.4. Sandcastle Documentation Generation Tools

Sandcastle is a set of tools published by Microsoft that act as documentation compilers. These tools can be used to easily create very professional-looking external documentation in Microsoft-compiled HTML help (.CHM) or Microsoft Help 2 (.HxS) format. At the time of writing, Sandcastle was still beta software and had been released only as a Community Technology Preview (CTP).

NDoc, an open source project, is another well-known documentation generator. Although NDoc was widely used, it never gained much financial or contributor support as an open source project. In June 2006, the creator of NDoc, Kevin Downs, announced he was discontinuing work on the project.

The primary location for information on Sandcastle is the Sandcastle blog at http://blogs.msdn.com/sandcastle/. There is also a project on CodePlex, Microsoft's open-source project hosting site, at www.codeplex.com/Sandcastle/. You can find a discussion forum and a link to download the latest Sandcastle installer package on this site.

By default, Sandcastle installs to c:Program FilesSandcastle. When it is run, Sandcastle creates a large number of working files and the final output file under this directory. Unfortunately all files and folders under Program Files require administrator permissions to write to, which can be problematic particularly if you are running on Windows Vista with UAC enabled. Therefore it is recommended that you install it to a location where your user account has write permissions.

Out of the box, Sandcastle is used from the command-line only. There are a number of third parties who have put together GUI interfaces for Sandcastle, which are linked to on the Wiki.

To begin, open a Visual Studio 2008 Command Prompt from Start Menu All Programs Microsoft Visual Studio 2008 Visual Studio Tools, and change the directory to <Sandcastle Install Directory>Examplessandcastle.

The Visual Studio 2008 Command Prompt is equivalent to a normal command prompt except that it also sets various environment variables, such as directory search paths, which are often required by the Visual Studio 2008 command-line tools.

In this directory you will find an example class file, test.cs, and an MSBuild project file, build.proj. The example class file contains methods and properties that are commented with all of the standard XML comment tags that were explained earlier in this chapter. You can compile the class file and generate the XML documentation file by entering the command:

csc /t:library test.cs /doc:example.xml

Once that has completed, we are now ready to generate the documentation help file. The simplest way to do this is to execute the example MSBuild project file that ships with Sandcastle. This project file has been hard-coded to generate the documentation using test.dll and example.xml. Run the MSBuild project by entering the command:

msbuild build.proj

The MSBuild project will call several Sandcastle tools to build the documentation file, including MRefBuilder, BuildAssembler, and XslTransform.

You may be surprised at how long the documentation takes to generate. This is partly because the MRefBuilder tool uses reflection to inspect the assembly and all dependent assemblies to obtain information about all of the types, properties, and methods in the assembly and all dependent assemblies. In addition, anytime it comes across a base .NET Framework type, it will attempt to resolve it to the MSDN online documentation in order to generate the correct hyperlinks in the documentation help file.

The first time you run the MSBuild project, it will generate reflection data for all of the .NET Framework classes, so you can expect it to take even longer to complete.

By default, the build.proj MSBuild project generates the documentation with the vs2005 look-and-feel, as shown in Figure 9-3, in the directory <Sandcastle Install Directory>Examplessandcastlechm. You can choose a different output style by adding one of the following options to the command line:

/property:PresentationStyle=vs2005
/property:PresentationStyle=hana
/property:PresentationStyle=prototype

Figure 9.3. Figure 9-3

The following listing shows the source code section from the example class file, test.cs, which relates to the page of the help documentation shown in Figure 9-3:

/// <summary><c>Increment</c> method increments the stored number by one.
/// <note type="caution">
/// note description here
/// </note>
/// <preliminary/>
/// </summary>
public void Increment()
{
   number++;
}

The default target for the build.proj MSBuild project is "Chm", which builds a CHM-compiled HTML Help file for the test.dll assembly. You can also specify one of the following targets on the command line:

/target:Clean  - removes all generated files
/target:HxS    - builds HxS file for Visual Studio in addition to CHM

The Microsoft Help 2 (.HxS) is the format that the Visual Studio help system uses. You must install the Microsoft Help 2.x SDK in order to generate .HxS files. This is available and included as part of the Visual Studio 2008 SDK.