Building Help Files with Sandcastle
XML documentation comments allow useful descriptive information to be attached to types and their members. This information is displayed within Visual Studio whilst coding but sometimes it is more useful to produce documentation as help files.
In an earlier article I described the basic techniques for adding XML documentation comments to your code and compiling them into an XML file. The file is used by Visual Studio to provide you with documentation as you code, either through Intellisense or other code windows. This can be very useful but sometimes you will want to produce help files describing your libraries that can be read without access to Visual Studio and distributed to your users.
Microsoft have created a tool named, "Sandcastle", which can be used to parse documentation XML files and compile the information into help files in various formats. The tool understands all of the types of XML comment and automatically produces help files with links between topics and to on-line documentation for .NET framework elements. The results are similar to those that you can see within the MSDN Library. Unfortunately, Sandcastle is not a simple tool to use. It is command-line driven with many options to choose from and requires a series of steps to be executed to produce the final result. It also has several dependencies that must be installed before it can be used.
The use of Sandcastle can be simplified using a tool named, "Sandcastle Help File Builder" (SHFB), developed by Eric Woodruff. Not only does the tool make it easy to generate help files using a flexible graphical user interface (GUI), it also guides you through its installation and the installation of all required dependencies. In this article I'll describe the installation process for SHFB and the basic steps required to generate a help file from an XML file.
Installing Sandcastle Help File Builder
The first step to install SHFB is to download the software. To do so, visit the SHFB project pages within the codeplex web site at http://shfb.codeplex.com/. When you visit the site you should navigate to the Downloads page and download the guided installation file. At the time of writing this is a 28MB zip file.
After extracting the zip file, run the executable, "SandcastleInstaller.exe". This will guide you through a series of steps. Some of the steps will scan your computer for Sandcastle's dependencies. When a required component is missing, you will be given the option to install it. Some steps may require additional downloads. As a minimum, make sure that you install the .NET framework version 4.0, Microsoft HTML Help Workshop, Sandcastle, the Sandcastle patch and Sandcastle Help File Builder.
Once the installation is complete you will find a new section has been added to the Start menu. You can launch SHFB by selecting, "Sandcastle Help File Builder GUI".
Creating a Project
SHFB uses project files to hold the information required to generate documentation. When you launch SHFB no project is loaded initially. To create a new project, open the File menu and select, "New Project". You will be asked to provide a name for the project file and to select the folder where you wish to place it. Once this step is complete, the project's properties are displayed. The window should appear similar to the image below:
You can see that there are a lot of options available that can be used to customise the final help file output. A description of all of these properties is beyond the scope of this basic article. We will use only the default settings to create a help file.
Adding a Documentation Source
To tell SHFB which XML file you wish to convert you can add a documentation source. To do so, right-click the Documentation Sources branch of the project tree within the Project Explorer pane. Select "Add Documentation Source" from the context-sensitive menu that appears. A dialog box will be opened to allow you to browse the file system and select the XML file that contains your project's documentation comments.
Compiling the Help File
With the documentation source added you can build the help file. First take a look at the OutputPath property. This determines where the outputted help file will be stored. By default the output location is set to ".\Help\", meaning that the file will be generated within the "Help" subfolder of the folder containing the SHFB project file. If you would like to create it elsewhere, change this value. Next, choose "Build Project" from the Documentation menu.
Building a help file in Windows' CHM format can take a few moments. During the process you will see the output from the various tools that are used. It is likely that you will see some warnings and other lines of information. These do not usually indicate a problem.
Once the process is complete you can view the generated help file by selecting "View Help File" from the Documentation menu. You can also open the target folder and double-click the created help file to see the results.
1 February 2012