Help Docs Using Sandcastle

I am currently on the bench at work waiting for my next assignment to start up in a few days.  Rather than sit around, read blogs and listen to podcasts, I’m keeping myself busy by putting together the beginnings of a code library to be shared across our development team.  Yesterday I started the foundation.  I defined the framework, file system layout and basic namespace conventions.  I also created two class libraries and associated test projects to get the ball rolling.  I’m pleased with the way the common library is turning out.

Today, I refactored a bit and then focused on documentation.  Specifically, I generated help file documentation via the XMLSummary comments. I searched around and played with various utilities and ultimately decided on Sandcastle and Sandcastle Help File Builder.

Sandcastle – Documentation Compiler for Managed Class Libraries, created by Microsoft, produces accurate, MSDN style, comprehensive documentation by reflecting over the source assemblies and optionally integrating XML Documentation Comments. Sandcastle works with or without authored comments and supports .NET Framework 1.1, 2.0, 3.0 and 3.5.  Sandcastle is, however, a command line based tool which has no GUI front-end.  That’s where Sandcastle Help File Builder (SCHB) comes in.  SCHB provides a user interface (as well as command line based tools) to facilitate the building of help files in an automated fashion. Both applications may be found on Codeplex.

Sandcastle (really Sandcastle Help File Builder wrapped around Sandcastle) is easy to install and navigate and I was able to quickly integrate into the common libraries’ best practices.  Now when additional code (new library, class, method, etc) is appended to our common code repository, team members simply need to follow the overall folder structure, code library templates/namespaces and update the Help File Builder project which is now in place.

Below are the instructions on how to extend the existing Help File Builder project.  These instructions will be share with my team members though they can easily be altered to create a help file from the ground up:

1. Download and install Sandcastle and Sandcastle Help File Builder from Codeplex.
2. Apply XML comments to your code base. 
3. Navigate to the Build Tab of your project’s properties and do the following:
   • Check XML documentation file
   • Set file name to bin\[mode]\assembly name.xml where [mode] is debug or release. Example: bin\release\MyCompany.Common.Serialization.xml
4. Compile your assemblies in release mode.   Note: I’m opting to only generate documentation per the assemblies/xml generated in release mode although it doesn’t have to be this way.
5. Run Sandcastle Help File Builder. The existing Sandcastle Help File Builder project can be found in the following location: MyCompany\Common\MyCompany.Common.shfb
6. Add your compiled assembly to the SCHB project:
   • Click Add > Browse to the libraries’ bin\Release > Select dll
   • After the assembly is added, the dll and xml files will be listed in the ‘Assemblies to Document’ list box. 
7. Document the assembly’s namespace by clicking on the ‘Namespaces’ button and editing the summary.
8. The MyCompany.Common.shfb project is already configured so there’s no need to change any of the project properties. For future reference, all non-default values are highlighted in bold font within the property list. This information is most obvious if you toggle the project properties to display Alphabetically rather than Categorized.Here’s a list of the settings which have been updated:
   • Help Title=MyCompany.Common Class Library
   • HtmlHelpName=MyCompany.Common
   • KeepLogFile=False
   • OutputPath=./
   • PresentationStyle=vs2005
   • SdkLinkType=Index
9. Generate the help file by clicking the Generate button in the toolbar.
10. View the help file by double-clicking the MyCompany/common/MyCompany.Common.chm or by opening the file via the SCHB Documentation/View help file menu option.

Again, I found the tools easy to use though I did encounter one gotcha. My file path included a folder named “.NET 3.5″.  I found that Help File Builder didn’t like the naming convention.  Apparently the preceding “.” caused the issue.  Once I renamed the folder to “NET 3.5″ everything worked like a charm.

References:

• http://bloggingabout.net/blogs/jschreuder/archive/2007/03/20/using-sandcastle-is-increasingly-mature.aspx