Click here to Skip to main content
Click here to Skip to main content
Go to top

Getting Started with Sandcastle

, 4 Nov 2008
Rate this:
Please Sign up or sign in to vote.
Install and build your first Sandcastle Help Document easily

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:

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.

I Suggest You Also Read

History

  • 4th November, 2008: Initial post

License

This article, along with any associated source code and files, is licensed under The Code Project Open License (CPOL)

Share

About the Author

stodgey

Canada Canada
No Biography provided

Comments and Discussions

 
Generalok article PinmemberDonsw7-Feb-09 13:19 
GeneralRe: ok article Pinmemberstodgey9-Feb-09 5:24 
GeneralRe: ok article PinmemberDonsw9-Feb-09 10:12 
GeneralRe: ok article Pinmemberstodgey9-Feb-09 10:18 
Generalxml Doc output in Express versions PinmemberKent K11-Nov-08 11:54 
GeneralFilename for XML file PinmemberRoland Bär5-Nov-08 4:08 
GeneralRe: Filename for XML file Pinmemberstodgey5-Nov-08 6:21 
GeneralProblems with instruction PinmemberDries de Groot4-Nov-08 22:10 
GeneralRe: Problems with instruction Pinmemberstodgey5-Nov-08 6:20 
GeneralEnhancing the documentation experience [modified] PinmemberThomas Weller4-Nov-08 21:58 
GeneralRe: Enhancing the documentation experience PinmemberDmitri Nesteruk5-Nov-08 0:48 
GeneralRe: Enhancing the documentation experience PinmemberThomas Weller5-Nov-08 1:17 
GeneralRe: Enhancing the documentation experience Pinmemberstodgey5-Nov-08 8:23 
General"this is best IMO" Pinmemberagorby4-Nov-08 20:22 
JokeRe: "this is best IMO" Pinmembergeo_m4-Nov-08 21:36 

General General    News News    Suggestion Suggestion    Question Question    Bug Bug    Answer Answer    Joke Joke    Rant Rant    Admin Admin   

Use Ctrl+Left/Right to switch messages, Ctrl+Up/Down to switch threads, Ctrl+Shift+Left/Right to switch pages.

| Advertise | Privacy | Mobile
Web02 | 2.8.140916.1 | Last Updated 4 Nov 2008
Article Copyright 2008 by stodgey
Everything else Copyright © CodeProject, 1999-2014
Terms of Service
Layout: fixed | fluid