Getting Started with Sandcastle

Introduction

This article will take you through the steps from installing Sandcastle to generating your first Sandcastle Help Document. It is assumed you already know how to generate XML comments within Visual Studio and what Sandcastle is.

Background

Documentation is always something that some programmers like to cry and moan about (well at least I do). When someone asks me how I did something I say 'I dunno, and who cares? It does what it's supposed to do!'. Well documentation insists we have an answer to this question. Visual Studio makes documenting easy as WELL as useful! Pressing (/) three times allows you to create XML comments for entering function data. This is not only useful for intellisense, but documentation as well.

Sandcastle is a program that turns the 'would be' painful documentation process into a few clicks of the mouse button (aside from adding XML comments). Currently there is no formal documentation for getting up and running with Sandcastle. So to save you the headache of searching the I-net like I had to do, I've created this tutorial.

Installation

To get started, you will need the following:

Visual Studio 2005 SDK
Sandcastle - Sandcastle back end
Sandcastle Help File Builder - One of many front ends for Sandcastle (this is best IMO)
HTML Help Workshop - To view Help Documentation

Building Your Help Documentation

Visual Studio Setup

Before you can build your documentation, you have to ensure to build your XML documentation file. The file is useless on its own; however, Sandcastle requires it in order to build the help doc.

In Visual Studio 2005, go to Project -> Properties and select the Build tab and ensure the XML documentation checkbox at the bottom under Output is checked:

It is important to note that the XML file should be in the format 'mylibraryname'.xml! In this example the library name is 'Sample'. You can now build the project and you are ready to export as a Sandcastle Help Document.

Sandcastle Help File Builder

Open the Sandcastle Help File Builder (SHFB) from your Start -> Program Files.
Within the Sandcastle Help File Builder, select Project -> New Project from Visual Studio Project... and open the *.sln from which you built your XML Documentation in the previous step (Visual Studio Setup).
Define the Help file Format within the HelpFileFormat Property in the Project Properties Window within SHFB. (Select Help1xAndWebsite because the website looks best IMO).
Define the OutputPath Property. (Project Properties Window)
Select Documentation -> Build Project

That is it, you are finished. You can load the *.chm file via the HTML Help Workshop program you've installed or, if you've exported as a website, you can open the index.html file. Both of these files are located in the directory you specified in the OutputPath property of the SHFB.