Generating MSDN style documentation using Sandcastle

ScrewTurn wiki with hosted MSDN style API documentation

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

SandCastle Help File Builder GUI

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?

4 thoughts on “Generating MSDN style documentation using Sandcastle

  1. I’ve used SandCastle to document an API that I did for an in-house project to provide our .NET developers access to some Win32 Delphi data structures. I tried to use the SandCastle binaries directly, but quickly gave up and quickly grabbed SandCastleGui. I want to look at SHFB and see if it has anything over SandCastleGui.
    It would be great if SandCastle would work on Win 32 Delphi projects, but not I’m not holding my breath waiting for that to happen. But it is a great tool for generating .NET documentation.

  2. Hi Chris,
    Thanks for the comment. Delphi’s comment format isn’t compatible with SandCastle. I work with Adam Markowitz who originally implemented the doc style commenting and there were some issues which lead to the incompatibility. Regardless, it’s a very nice feature to have.
    Thanks for the link to SandCastleGui I’ll have to check that out.

  3. Steve,
    Not to quibble, but I can’t make out much at the resolution of those images. Being able to click for a larger view would be very nice….

  4. Hey Bill,
    Yeah, the wiki image is intentionally vague. When I first posted you could click on the image and read the content however I realized after I posted that I don’t have permission from the client to publish that content so I decided to immediate yank the larger image. As for SHFB, that could have a larger image and if I get the chance I’ll update it.

Comments are closed.