Generating MSDN style documentation using Sandcastle

To the right is a screenshot of MSDN style documentation created using Microsoft’s SandCastle and SandCastle Help File Builder (SHFB) which is generated as part of a Continuous Integration build running under CruiseControl.NET shown here hosted within a page on a ScrewTurn wiki at a client’s site.

The documentation was created for the EDI Invoicing system I developed. Originally, I’d simply followed the Thoughtworks style for documenting Tasks and Source Control providers but that proved rather time consuming and required a fair amount of hand editing. Using this mechanism the documentation on the wiki is always up-to-date and I don’t have to worry about maintaining lots of static content.

SandCastle Help File Builder to the Rescue

Rather than using SandCastle, Microsoft’s oh-so-slowly-developing documentation tool for managed code, Eric Woodruff has created SHFB which gives SandCastle the user experience you’d expect from Microsoft itself. (btw, if you’re a Borland fan be sure to check out Eric’s Turbo Vision page for a trip down memory lane)

SHFB allows you to create a project, select the desired assemblies, and generated web based MSDN style documentation easily. In fact, SHFB allows you to select from three different web site styles. Be sure to read the Links to Resources section as there are a number of additional tools required. Of course, the same thing is possible with SandCastle itself and if you’re up for it check out this post for details.

Generating API Doc Under Continuous Integration

Since I didn’t want to have to manually regenerate the documentation I setup a CruiseControl.NET task to handle creating the documentation web site which also uses SHFB and looks like this:

<exec executable="C:\Program Files\EWSoftware\SHFB\SandcastleBuilderConsole.exe">
  <baseDirectory>c:\work\utilities\edi\help</baseDirectory>
  <buildArgs>vtalk.shfb</buildArgs>
  <buildTimeoutSeconds>2400</buildTimeoutSeconds>
</exec>

Adding this as a task ensures that the documentation is never out of date with the one minor downside being that the documentation isn’t available during the build but that’s really minor.

Conclusion

If you’ve been holding off using SandCastle or have been looking for tools to make it easier be sure to give SHFB a try as it worked like a charm for me.

What’s your experience with SandCastle been like? Have you tried it?