19 August 2006

Sandcastle - Building API Documentation

For anyone who has ever had to generate documentation for their .NET projects, you know only too well how difficult and time consuming that can be.

There have been a few utilities available in the past that helped out in this area.  One example is NDoc.  NDoc generates some very nice API documentation in several different formats.  However, it doesn't work so well for Visual Studio 2005.  Also, the original developer of NDoc has recently announced that he is dropping future development for NDoc in favor of Sandcastle (as well as other circumstances - although the project may be picked up and administered by another volunteer).

Microsoft's Sandcastle project may not be as extensive as NDoc in some areas (e.g. support for custom tags - at least not yet) but it appears that it will support the majority of everyone's needs out of the box with the ability to be extended as needed.

If you follow the various examples on creating Sandcastle documentation you'll find that it's rather tedious to setup the initial scripting necessary to generate your final help file.  However, there are some nice tools out there to help with this task as well.

So far, my favorite tool has to be Sandcastle Help File Builder - an open source utility available at The Code Project.  This utility has a UI that looks almost identical to that of NDoc and works in a similar fashion.  It allows you to simply refer to the assemblies you wish to document, set some custom properties, and generate your documentation.  If you're looking for a UI to interface with Sandcastle, this is the tool to look at.

Here are some various Sandcastle links:

  • The July 2006 CTP of Sandcastle can be downloaded here.
  • The official Sandcastle blog.
  • A quick example for running Sandcastle.
  • Sandcastle Help File Builder - the utility mentioned above.
  • A UI for creating a Sandcastle BAT file.  A nice utility if you want to generate a batch file that can then later be scripted.