Click here to Skip to main content
11,494,407 members (74,023 online)
Click here to Skip to main content

Getting Started with Sandcastle

, 4 Nov 2008 CPOL 27.6K 34
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 Pin
Donsw7-Feb-09 14:19
memberDonsw7-Feb-09 14:19 
GeneralRe: ok article Pin
stodgey9-Feb-09 6:24
memberstodgey9-Feb-09 6:24 
GeneralRe: ok article Pin
Donsw9-Feb-09 11:12
memberDonsw9-Feb-09 11:12 
GeneralRe: ok article Pin
stodgey9-Feb-09 11:18
memberstodgey9-Feb-09 11:18 
Generalxml Doc output in Express versions Pin
Kent K11-Nov-08 12:54
memberKent K11-Nov-08 12:54 
GeneralFilename for XML file Pin
Roland Bär5-Nov-08 5:08
memberRoland Bär5-Nov-08 5:08 
GeneralRe: Filename for XML file Pin
stodgey5-Nov-08 7:21
memberstodgey5-Nov-08 7:21 
GeneralProblems with instruction Pin
Dries de Groot4-Nov-08 23:10
memberDries de Groot4-Nov-08 23:10 
GeneralRe: Problems with instruction Pin
stodgey5-Nov-08 7:20
memberstodgey5-Nov-08 7:20 
GeneralEnhancing the documentation experience [modified] Pin
Thomas Weller4-Nov-08 22:58
memberThomas Weller4-Nov-08 22:58 
GeneralRe: Enhancing the documentation experience Pin
Dmitri Nesteruk5-Nov-08 1:48
memberDmitri Nesteruk5-Nov-08 1:48 
GeneralRe: Enhancing the documentation experience Pin
Thomas Weller5-Nov-08 2:17
memberThomas Weller5-Nov-08 2:17 
GeneralRe: Enhancing the documentation experience Pin
stodgey5-Nov-08 9:23
memberstodgey5-Nov-08 9:23 
General"this is best IMO" Pin
agorby4-Nov-08 21:22
memberagorby4-Nov-08 21:22 
JokeRe: "this is best IMO" Pin
geo_m4-Nov-08 22:36
membergeo_m4-Nov-08 22: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 | Terms of Use | Mobile
Web03 | 2.8.150520.1 | Last Updated 4 Nov 2008
Article Copyright 2008 by stodgey
Everything else Copyright © CodeProject, 1999-2015
Layout: fixed | fluid