Archive for the ‘Uncategorized’ Category

Automate the creation of a MSDN-style documentation website with Sandcastle (Introduction)

January 21, 2008

One of the cool things about the Microsoft.NET platform is how easy it is to create great code documents via XML comments (follow the link for a great guide).  With little effort, not only do you get immediate intellisense support but also the ability to generate MSDN-style documentation for use by you, your workmates, and anyone else who programs against your code. 

The crappy thing about XML comments is that it is currently not at all easy to get those comments out of your binaries and into a useful format.  There are three main format types:  CHM (compiled HTML help), HsX (Visual Studio’s Help 2 format) and plain old HTML.

There are tools available to help you extract XML comments from code and generate help documentation, almost all of which center around Microsoft’s Sandcastle project.  Unfortunately, Sandcastle is currently a beta project (though open source).  That means if you want to use it you can expect the learning curve to be high and the chance of failure to be great.  But there are a few support projects out there that aim to make using Sandcastle easier.  To create a documentation website I use one of these tools, the Sandcastle Help File Builder, a project maintained by Eric Woodruff.

One of my recent goals at work was to configure my daily release build to automatically generate a documentation website, which could be accessed easily from a link on our internal dev wiki (hosted on ScrewTurn’s excellent ASP.NET wiki platform).  That way fresh docs will always be available for review.  Reviewing our documentation is an important part of our build process.  Its one of those things that if you don’t do it early and often it will never get done.  And as one of our goals is to provide a decent API for external coders to use when building add-ins for our project, good documentation will save lots of time down the road.

Setting all this up is a complicated process, so I’m going to split it up among a number of different posts.  I’ve created a number of snapshots of the process to help make understanding it easier.  The first step is identifying the requirements for setting this up in the first place. 

Prerequisites for configuring Team Build to automatically generate a documentation website:

  1. Team Foundation Server
    • This guide uses TFS 2005 workgroup edition; I haven’t tried to do this using 2008
  2. A functioning website
    • My website is an internal wiki
    • Its located on the same server as the TFS, but it could be on another machine
    • Documentation is published to a shared folder on the network that is mapped to a virtual directory within the website
  3. A build machine
    • We have a standalone machine for building, but it can be the same machine that hosts TFS and the website
    • Our build machine is named Bob, as he builds. Yours may be named differently.
  4. Sandcastle
    • I used the October CTP of Sandcastle as it is stable and works with the currently available version of SHFB (Sandcastle Help File Builder)
    • Must be installed on the build machine
  5. Sandcastle Help File Builder
  6. A Team Build
    • My Team Build is a release build that gets kicked off daily at around 3am
    • There are plenty of guides out there for creating daily builds (all of which probably better than the first three hits in Google)

If you have got all these things already, or are planning on setting them up to perform a daily build that generates a documentation website, then this guide is for you.  If you want to automatically build CHM help files, or HsX files for installation along with your SDK, this guide will be somewhat relevant to your interests.  You’ll have to change your SHFB configuration and add in some additional build tasks.  Those are beyond the scope of these posts.  Good luck on it. 

If you’ve met the requirements so far, great.  Next step:  getting your team build ready to start generating your help website.