Click here to Skip to main content
14,664,421 members
Articles » Platforms, Frameworks & Libraries » .NET Framework » General
Article
Posted 4 Nov 2008

Stats

38.7K views
34 bookmarked

Getting Started with Sandcastle

Rate this:
3.29 (7 votes)
Please Sign up or sign in to vote.
3.29 (7 votes)
4 Nov 2008CPOL
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:

Image 1

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 13:19
MemberDonsw7-Feb-09 13:19 
GeneralRe: ok article Pin
stodgey9-Feb-09 5:24
Memberstodgey9-Feb-09 5:24 
GeneralRe: ok article Pin
Donsw9-Feb-09 10:12
MemberDonsw9-Feb-09 10:12 
GeneralRe: ok article Pin
stodgey9-Feb-09 10:18
Memberstodgey9-Feb-09 10:18 
Generalxml Doc output in Express versions Pin
Kent K11-Nov-08 11:54
professionalKent K11-Nov-08 11:54 
GeneralFilename for XML file Pin
Roland Bär5-Nov-08 4:08
MemberRoland Bär5-Nov-08 4:08 
GeneralRe: Filename for XML file Pin
stodgey5-Nov-08 6:21
Memberstodgey5-Nov-08 6:21 
GeneralProblems with instruction Pin
3sL4-Nov-08 22:10
Member3sL4-Nov-08 22:10 
GeneralRe: Problems with instruction Pin
stodgey5-Nov-08 6:20
Memberstodgey5-Nov-08 6:20 
GeneralEnhancing the documentation experience [modified] Pin
Thomas Weller4-Nov-08 21:58
MemberThomas Weller4-Nov-08 21:58 
GeneralRe: Enhancing the documentation experience Pin
Dmitri Nеstеruk5-Nov-08 0:48
MemberDmitri Nеstеruk5-Nov-08 0:48 
GeneralRe: Enhancing the documentation experience Pin
Thomas Weller5-Nov-08 1:17
MemberThomas Weller5-Nov-08 1:17 
I think you are misunderstanding something. I'm not proposing to build some software on top of DXCore and then selling it. What I mean is: you can install DXCore on your development machine for free and continue with your work. And this is perfectly legal - everything else would not make much sense anyway...

Quote from the DXCore license agreement:
DEVEXPRESS grants to you as an individual, a personal, nonexclusive license to install and use the SOFTWARE PRODUCT(S) for the sole purposes of designing, developing, testing, and deploying application programs which you create.
Smile | :)

This EULA is only aimed to prevent DXCore from becoming an integral part of a commercial 3rd party product in some way. No need to care about it here...

Regards
Thomas
GeneralRe: Enhancing the documentation experience Pin
stodgey5-Nov-08 8:23
Memberstodgey5-Nov-08 8:23 
General"this is best IMO" Pin
agorby4-Nov-08 20:22
Memberagorby4-Nov-08 20:22 
JokeRe: "this is best IMO" Pin
geo_m4-Nov-08 21:36
Membergeo_m4-Nov-08 21:36 

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

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