Let’s build a SandCastle

Currently we’re working on a small set of web services for Cork County Council which are to be used by 5 vendors for 8 applications.    As the number of vendors and meetings increased it became useful to provide thorough documentation.  Enter Sandcastle.

Sandcastle is Microsoft’s tool for generating MDSN documentation and will be included in the Orca SDK.  As you know code comments are automatically grabbed out of the code and placed in an XML file.  Sandcastle simply points to the assembly and xml file and is capable of compiling a stand-alone chm file or web site.  Sandcastle is currently available as a technical preview and is really coming along nicely.  There is a lot of interest in it especially as NDOC has been abandoned and does not support .NET 2.0.  Many tools have already been developed to make it easier to use (see below).  The latest version is the March 2007 Sandcastle CTP Technical Refresh which can be downloaded here:

http://www.microsoft.com/downloads/details.aspx?FamilyID=e82ea71d-da89-42ee-a715-696e3a4873b2&displaylang=en

 

The Sandcastle download on its own is not too useful and requires modifying a large batch file in order to run the many utils which eventually create the documentation.  For those familiar with NDOC, we have here a utility which provides a similar front-end GUI which makes the build process much easier and likely faster due to the level of configuration it exposes.  For example, for our project I turned off DocumentInheritedMembers and DocumentInheritedFrameworkMembers to a) highlight our methods and avoid confusion and b) greatly decrease help file build time (1.5 minutes vs 15 min with full framework reflection).  The Sandcastle Help File Builder can be downloaded here:

http://www.codeplex.com/SHFB/Wiki/View.aspx

 

Advertisement