A Guide to Sandcastle - Part 1 - Introduction

Generating documentation doesn't seem to be that of an important task for libraries developers use day by day. However, chances are that the comments introduced in the code itself aren't quite readable and easy-to-navigate. When an assembly grows quite big, it is harder to know exactly what's where, and that's the point were generated documentation can help a lot.

Sandcastle is an open-source documentation generation toolset that facilitates the process of creating MSDN-like help files for managed assemblies. It surprised me that there is no official documentation on the official page (there are, however, blog posts all around the web that describe the tool). I decided to write my own set of articles that will guide the reader from the very beginning to more advanced concepts. 

Today I am talking about the general setup and a test build for a Windows Phone 7 application.

Step 1: Download and Install Sandcastle

Head to the CodePlex and grab the most recent build (currently it is 2.6.1062.1). It is worth mentioning that the Visual Studio 2010 (and .NET Framework 4) documentation was built using tools included in Sandcastle - it is most definitely the most reliable documentation solution for .NET projects.

Once you install the toolset, nothing will ultimately change in Visual Studio and you won't see any additional menu items in the Start menu. This is normal - you just installed the raw (core) set of tools that is located in the folder you specified during the installation (in my case: C:\Program Files (x86)\Sandcastle).

Step 2: Look at what you have available

The folder structure you got should resemble something like this:

Here is a short explanation of what each folder contains.

Data - contains XML-formatted reflection data on general .NET assemblies. Used to generate documentation on existing types.

Examples - as the name states, there are existing documentation samples that can be used for reference purposes. Some of them require additional configuration in order to work.

Presentation - contains general styling information (for different doc types, like VS2005, Prototype or HANA).

ProductionTools - contains the actual tools that perform the documentation compilation.

ProductionTransforms - contains XSL stylesheets used to transform data XML to XHTML.

Schemas - contains XML schema files related to general data manipulations (content parsing).

The initial set of tools might be a bit confusing and it seems like it's pretty hard to use. To make this task easier, there is a third-party project available that binds to the existing tools and allows to use a GUI to easily build and customize help content.

Step 3: Download Sandcastle Help File Builder

That's exactly the tool I am talking about. You can get it on its official CodePlex page. It is extremely well documented and is pretty straightforward to use.

The installation process is mostly automated - you will still be able to pick what options exactly you want there. For now, you need to have the Sandcastle tools installed, as well as the Help Builder. .NET Framework is, of course, a must have.

Step 4: Launch SHFB (Sandcastle Help File Builder) and look around

Take a look at the UI - there are lots of options available to customize the documentation generating process. If you see a blank screen, make sure you create a new project in the application.

I should remind the reader that using the Sandcastle Help File Builder is not required to generate documentation using Sandcastle tools. It is merely a wrapper that automates many of the scripts that otherwise would have to be created and executed manually.

The main part of the screen is the property grid - that's where the developer is able to set what documentation types will be generated and what parts of the linked code base to be described. The properties listed are pretty self-descriptive and mostly don't require manual set-up (there are pre-defined choices available).

By default, on the right side there is the Project Explorer, where it is possible to add the managed projects for which documentation should be generated, as well as additional references tied to the projects themselves.

Documentation Sources should not be confused with the locations where documentation already exists (or is intended to be placed). It is, in fact, the branch responsible for keeping a list of current VS projects and managed assemblies.

Step 5: Add a sample Documentation Source to the project

Right click on Documentation Sources and click on Add Documentation Source.

Select an existing managed assembly or project. As I mentioned at the beginning of this article, I am going to work with a Windows Phone 7 application project, so that's what I am going to add.

Comment files (XML) can also be added as documentation sources.

In the properties grid, select the HelpFileFormat property and chose all four possible documentation formats - there will be four doc entities built for each separate format.

HtmlHelp1 is the old-style CHM format. MSHelp2 is the help format used with Visual Studio (2002 to 2008). MSHelpViewer is the help format used in Visual Studio 2010 (obviously, formatted to be viewed through the Help Viewer application). Website is the web-version (MSDN-like) of the same help documentation.

Right now I am picking all four options to show some very basic differences between the visualization formats. Later on I will discuss specific nuances related to each format.

Once done, select the Documentation -> Build Project menu option. You should see the progress being logged in a new tab.

IMPORTANT NOTE: Depending on the current versions of Visual Studio installed (or the associated SDKs), some options might fail. For example, if you are trying to compile a MSHelp2 project and you don't have Visual Studio 2008 installed (or the VS2008 SDK), you will be prompted with a message like this:

All you have to do in this case is go back to project properties and remove the unsupported format.

But there still might be problems even without incompatible formats. SHFB doesn't resove cross-references at design time, so if a project references a DLL that is not known to Sandcastle (remember the Data folder mentioned in the beginning), another set of exceptions will be thrown.

In case the location of the referenced assembly is known (or it is included in the GAC), right-click on the References branch in the Project Explorer and show the path to the missing assembly(ies).

Once all needed references are added (if that was the case), restart the build process and you should be able to see how the build successfully completes. Usually it might take a minute or two for it to get done depending on the project size and the number of cross-references.

When the build is completed, you don't need to leave SHFB in order to view existing documentation. Just go to Documentation -> View Help File and select the format you would like to view.

NOTE: If you have the .mshc file ready, you will need to install it in in the existing help library (with the Help Library Manager) in order to use it.

To give you a quick overview of what the content looks like, here are some snapshots of what was just generated. I must mention that I am using the HANA theme here, so don't worry if it doesn't exactly resemble the MSDN style - I am always able to switch back to a more conservative theme.

Web

CHM