Using Sandcastle to Generate Documentation
Sandcastle is Microsoft's documentation compiler. It uses reflection of source assemblies and integrates the XML comments placed in the code by the developer to generate comprehensive MSDN-like documentation. Actually, it is used internally by Microsoft to build the .Net Framework documentation.
The problem with Sandcastle's current version (October CTP) is that it's not very user friendly, since it does not include a graphical interface and the developer has to go through several steps to generate the documentation for his projects. Fortunately, the developer community has released a few helpful tools that do most of the work for you.
Here's how I do it…
Pre-Requisites
To use Sandcastle you only need two things (and probably, you already have them):
- .Net Framework 2.0 (Download it here)
- HTML Help Workshop (Download it here)
Of course, you need the latest release of Sandcastle (Download the October CTP here).
Graphical Interface
Download the latest version of Sandcastle Help File Builder (from here) and install it.
Generating the Documentation
After you installed all the pre-requisites, Sandcastle and the Help File Builder, you can start generating your documentation.
The only thing you must do is make sure that you build your assemblies with the XML documentation option. In Visual Studio 2005, follow these steps:
- Go to the properties page of you project
- Select the Build tab
- Check the XML documentation file option, in the Output section
- Define an output path and file name for the documentation file (or leave it with the default value)
- Compile your project
With this option, the compiler will build your assembly and output an XML file with all the developer comments. You can now use the Sandcastle Help File Builder and load the assemblies and their respective XML documentation files, and produce MSDN-like documentation as chm files.