How to: Generate source documentation using Sandcastle
I've blogged about Sandcastle a few times already (see these links) in the past year. Sandcastle is the Microsoft solution for generating Help files using the XMl documentation tags in your .Net code. I've decided I needed to post an update on the current status of Sandcastle, because I feel the tool is getting more mature. At present, the March CTP has just been released.
The reason for this new post was the new CTP and the improved Sandcastle Helper by Eric Woodruff. The new CTP contains numerous fixes. A large number of these fixes are related to the Orcas Beta 1 release. Sandcastle now supports building help files based on Orcas projects and correctly references Orcas assemblies.
The Sandcastle Helper is, by my opinion, still one of the better options to create a help file using Sandcastle. At first, the application featured only a Winforms GUI application which strongly resembles the infamous (but now deceased) NDoc application. There is now also a console application which uses the project files that you create using the GUI application. This gives you the option of including it in a postbuild event in your Visual Studio project. The application also helps you add references to GAC assemblies you use in your solution. Sandcastle needs these references so that reflection will help extract information about objects used from these GAC assemblies.
In this post I will try to give you a short introduction for when you want to use Sandcastle and the Sandcastle Helper.
Quickstart
So let's have a quick look in how you can use Sandcastle for generating your documentation. You must first install the CTP and the Sandcastle Helper:
Step 1 - Make sure the project creates an XML document
Now let's assume you have a .Net assembly called ClassLibrary1 which contains the following sample class:
using System;
using System.Collections.Generic;
using System.Text;
namespace ClassLibrary1
{ /// <summary>
/// A sample class to show something using Sandcastle
/// </summary>
public class SampleClass
{ private string _propertyValue;
/// <summary>
/// Gets or sets the property value.
/// </summary>
/// <value>The property value.</value>
public string Property
{ get
{ return _propertyValue;
}
set
{ _propertyValue = value;
}
}
/// <summary>
/// Determines whether the property is null.
/// </summary>
/// <returns>
/// <c>true</c> if property is null; otherwise, <c>false</c>.
/// </returns>
public bool IsPropertyNull()
{ bool result = false;
if (this.Property == null)
{ result = true;
}
return result;
}
/// <summary>
/// Determines whether the property is null.
/// </summary>
/// <returns>
/// <c>true</c> if property is empty; otherwise, <c>false</c>.
/// </returns>
/// <example>
/// This example shows how you might use this method:
///
/// <code>
/// SampleClass sample = new SampleClass();
///
/// if (sample.IsPropertyEmpty())
/// { /// Console.WriteLine("The property is empty"); /// }
/// else
/// { /// Console.WriteLine("The property contains value " + sample.Property); /// }
/// </code>
/// </example>
public bool IsPropertyEmpty()
{
bool result = this.IsPropertyNull();
if (!result)
{ result = (Property.Trim().Length == 0);
}
return result;
}
}
}
Never mind rather silly looking code, it's just to demonstrate Sandcastle ;-). I'm assuming everybody knows this, but make sure you check the XML documentation file check box on the Build tab in your project properties window:
Step 2 - Compile the assembly
Now compile the class library. You should see the ClassLibrary1.XML in the Debug directory.
Step 3 - Run the Sandcastle Help File Builder
Next thing to do is start the Sandcastle Help File Builder. You should see the following window:
Step 4 - Add assemblies to the Sandcastle Help File Builder project
To create a help file, all you need to do now is click the Add button and select the compiled assembly for the class library. The Assemblies to Document list box should then show the assembly you compiled, and the XML file containing the documentation information that the .Net compiler extracted from your code.
Step 5 - Set additional properties
In the Project properties panel of the application you should change the following properties:
- Presentation Style. Set this to VS2005
- SDK Link type. Set this to Index
Step 6 - Generate the help file
Last step is to click on the generate button in the toolbar:
The application will then run all Sandcastle tools in the correct order to generate a help file.
Step 7 - View generated help file
When the help file is compiled, you can view the result by selecting View Help File from the Documentation menu. The documentation for the method IsPropertyEmpty in the above sample class will look like this:
