Sandcastle Help File Builder - generate documentation for .Net

Sandcastle Help File Builder is a graphical shell over the Sandcastle documentation generator. In turn, Sandcastle is a flexible and feature-rich .Net documentation generator using XML comments from source code. We will use this and in several steps we will create the documentation of our project.

Main features of Sandcastle

• Inclusion in the documentation of XML comments from the source code.
• Automatically retrieve information about .Net elements, such as classes, methods, properties, enumerations using reflection .
• The ability to integrate your additional HTML pages into the documentation.
• Documentation generation in several formats: Microsoft Compiled HTML Help (CHM), MS Microsoft Help 2 (MSDN), the website is static and dynamic with search (ASP.NET).

Sandcastle makes extensive use of XML and transformations using XSLT in its work. Everything is implemented very flexibly, easily customizable and available as source codes.

Preparation for work

To create the documentation we need to install the latest stable versions:

• Sandcastle May 2008 Release (Version 2.4.10520)
• Sandcastle Help File Builder 1.7.0.0 Production

Test project for documentation

In my case, I will not complicate the example and make documentation for the “Hello World!” Application. The documentation will contain a description of the classes used, namespaces, the start page, and an additional information page about the application.
Our main class console application:

using System;
using System.Text;

namespace Atv.Research.HelloWorld
{
/// <summary>
///
/// </summary>
public class Program
{
/// <summary>
///
/// </summary>
/// <param name="args"> </param>
public static void Main( string [] args)
{
Console .Out.WriteLine( "Hello World!" );
}
}
}

* This source code was highlighted with Source Code Highlighter .

In the project properties you need to set the generation of the XML file with our comments. To do this, in the context menu on the project Properties / Build tab / section of the Output - set a tick for the "XML documentation file". After compiling the project, we will receive our application Atv.Research.HelloWorld.exe and a file with comments Atv.Research.HelloWorld.XML .

Let's immediately add a couple of static pages to our documentation. It often happens that technical information from the code is not enough. More general descriptions are needed, with pictures and diagrams. Or, for example, you need to insert the entire text of the configuration file or WSDL for the web service. As an example, we will insert 2 static HTML pages. One of them will be the starting point for our documentation.
')
Index.htm

<! DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd" >
<!-- @DefaultTopic -->
< html xmlns ="http://www.w3.org/1999/xhtml" >
< head >
< title > About </ title >
</ head >
< body >
< div style ="height:140px;" >   </ div >
< div style ="text-align:center" >
< h1 > < br /> Hello World! </ h1 >

< div >< a href ="Details.htm" > </ a ></ div >
</ div >

</ body >
</ html >

* This source code was highlighted with Source Code Highlighter .

Details.htm

<! DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd" >
< html xmlns ="http://www.w3.org/1999/xhtml" >
< head >
< title > Details </ title >
</ head >
< body >
< h2 > </ h2 >
< p > "Hello World" Sandcastle. </ p >
< h2 > </ h2 >
: < see cref ="Atv.Research.HelloWorld.MyTestClass" />

< h2 > "The Code Block Component" </ h2 >
< pre lang ="cs" numberLines ="true" outlining ="true"
title ="Example of Syntax Highlighting" >
// Test method
public void TestMethod(string s, int x)
{
// Debug code
x = x + 1;
s = x.ToString();
Console.WriteLine("The string = " + s);
}
</ pre >

</ body >
</ html >

* This source code was highlighted with Source Code Highlighter .

Here you should pay attention to the following:

• @DefaultTopic - a comment is used to indicate that this page will be the starting page.
• The <see> tag will help refer from a static page to a page of automatically generated source code documentation containing a specific class, method, or namespace.
• The <pre> tag will make syntax highlighting in code examples for static pages.

These and other built-in features are described in the Sandcastle Help File Builder documentation.

Run the program

Actually, we already have input data. This is our application, an XML file with comments and 2 static pages for describing our application. It's time to launch the Sandcastle Help File Builder GUI.

The main window of the program "Sandcastle Help File Builder GUI"

1. We add our assemblies and XML files with documentation, in our case these are Atv.Research.HelloWorld.exe and Atv.Research.HelloWorld.XML .
2. Add a general description of the project.
3. Add a description of the namespaces, properly structured and described - they help to better navigate the project. All this information will be reflected in the received documentation.
4. Perform project settings. I will list only the mandatory and those that should be paid attention at once.
   

   Parameter	Value	Description
   Additional and Conceptual Content
   AdditionalContent	In the additional window that opens, add our Index.htm and Details.htm pages using the File button.	Additional static HTML pages.
   Build
   ComponentConfigurations	Select the Code Block Component in the window that opens.	We use it to highlight syntax from a static page.
   FrameworkVersion	2.0.50727	Specify the .Net version used in the application here.
   HelpFileFormat	Help1xAnd2xAndWebsite	Select one or more output formats: HtmlHelp1x / HtmlHelp2x / WebSite.
   Help File
   HelpTitle	Test console application	Our headline
   HtmlHelpName	HelloWorldApplication	Help Output File Name
   PresentationStyle	vs2005	At this point, your preference, I am accustomed to "vs2005" instead of "hana" or "Prototype"
   RootNamespaceContainer	True	We will separate our class descriptions into a separate help site.
   RootNamespaceTitle	Namespaces	and give him our name
   Paths
   HtmlHelp1xCompilerPath	C: \ Program Files \ HTML Help Workshop \	HTML Help Path Workshop and Documentation
   HtmlHelp2xCompilerPath	C: \ Program Files \ Common Files \ Microsoft Shared \ Help 2.0 Compiler \	The path to the "Microsoft Help SDK" that is installed with the Visual Studio SDK (2003/2005/2008), for example, Visual Studio 2008 SDK 1.1
   Outputpath	. \ HelpResult \	The path where the finished documentation will be copied
   Sandcastlepath	C: \ Program Files \ Sandcastle \	The path to Sandcastle, adjust it according to your settings
   Workingpath	. \ SandcastleWorkingFolder \	Path to the working folder where intermediate work results will be added

   Additionally, you can customize the text that will be displayed on each page at the top and bottom, a copyright line and links for feedback. Specify whether to document private and protected methods and properties. Enable alerts when there is no XML comment in the code. A detailed description of the settings you will always find in the accompanying documentation. But do not forget that “Sandcastle Help File Builder” is a graphical add-on for Sandcastle, and you can use it directly if necessary.
   
5. Save the project for reuse.
6. We build documentation.

Work results

1. Microsoft Compiled HTML Help (CHM)

CHM Help


CHM Help - Static Page

2. MS Microsoft Help 2

Integrated MSDN Help

3. Static website

Help in the form of ordinary HTML pages

4. Dynamic website (ASP.NET)

Help in the form of a dynamic site with search

Additional Information

All the codes used above, the Help File Builder project and the results of its work can be found in the SandcastleTestProject.zip archive on narod.yandex.ru or drop.io (391KB).

Links for further study:

• Sandcastle on CodePlex
• Sandcastle Help File Builder at CodePlex
• XML documentation in C # on Habré

I showed only the basic features of Sandcastle. I hope that you were interested and if you have not used it yet, now you will try. Thanks for attention.