This is the first in a 3-part series on using the Sandcastle tools to produce great looking (and hopefully useful) internal documentation. In this post we cover the basics of Sandcastle and how to get up and running with it.

Before we start, if you are not familiar with the XML commenting system then you should skim this primer. Also, we won’t be discussing any of the XML comment tags - for background on the supported tags either check out this excellent resource, or wait for the Professional Visual Studio 2008 book

Sandcastle uses two mechanisms to gather the data it requires to produce the documentation. Firstly, it uses reflection to discover all the public types, methods, and properties in a source assembly. Secondly, it optionally integrates any XML documentation comments. So basically this means that you can generate basic documentation with no XML comments, and really great documentation with a bit of inline XML commenting.

Firstly, download and install the latest Sandcastle package (at the time of writing this was the October 2007 CTP) . You can find a link to download the latest Sandcastle installer package on the Sandcastle Wiki.

By default, Sandcastle installs to c:\Program Files\Sandcastle. 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.

To begin, open a Visual Studio 2008 Command Prompt and change directory to <Sandcastle_Install_Directory>\Examples\sandcastle\.

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. 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 a 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 dependant assemblies to obtain information about all of the types, properties, and methods in the assembly and all dependant 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 in compiled help (CHM) format as shown below.

This post covered the basics of Sandcastle and how to get up and running with it and generate a CHM documentation file.

Part II provides an overview of the Sandcastle template system, which is what controls the look-and-feel of the final documentation.

Part III will cover how to generate documentation in the Microsoft Help 2 (HxS) format, which is the format that the Visual Studio help system uses.