Automate the creation of a MSDN-style documentation website with Sandcastle (Part 1 of 3)

Before I start, I’d just like to apologize about the quality of the images.  I took snapshots during the configuration process to document it for myself and other people at work.  Consequently, the images contain a fair amount of detail about the internal projects I’m working on.  I have blurred anything that might reveal information about our internal development process.  I did this not because we’re working on super secret stuff, but because I’d rather be safe than sorry.  Standard, mundane things are left unblurred (yes, we access data and log messages within our applications).  Also, if an image is too small to view, you can click it to see it full size.

(This is part one of a three part series on how to automate the creation of a documentation website using Team Foundation Server Build, Sandcastle, and Sandcastle Help File Builder.  If you haven’t read the introduction, go do so.  It outlines what you need to have before you can start.)
The first thing you need to do is to prepare a Team Build type that will be configured to automatically create your documentation website.  In my example, I’m using my Release build, which is run every night.
This Release build, strangely enough, uses the Release configuration.  I’ve set up the Release configuration so that none of the test projects within the solution are built.   You might want to do this as well; normally you wouldn’t want your test projects to be included in your documentation.  If you want to customize your configuration, you can access the Configuration Manager from the Build menu, from the Solution Property Pages dialog box, or from the solution configuration drop-down in the main toolbar.

If you want to do the website creation during, say, a continuous integration build where your test projects are built, you can exclude the test binaries from documentation later by not selecting those binaries within the SHFB configuration.

Next, you need to configure each project you wish to include in the documentation website to generate an XML documentation file.  I’m not exactly sure if this step is necessary, but I did this and everything works as I expected so you should probably do it too.
You will need to do this for every project you wish to generate documentation for within your solution.  You can configure this via the Project Properties editor.  There is a check box for XML documentation creation at the bottom of the Build tab.  Just check the box and leave the path and name for the resulting file with the default value.

The XML document file generated contains all your XML comments in… XML format.  If your XSL chops are good, this might be the last step for you.  Hypothetically, you could use a transform to generate W3C standards compliant XTHML files directly.  However, most of us mortals are only good at fifty seven out of the sixty core technologies we need to master as developers.  That’s where Sandcastle and the Sandcastle Help File Builder come in.  They do the heavy lifting so you can sit back, looking good holding a beer after work.
Now that your build is created and your configuration is set, go ahead and run the Team Build.  You need to do this at least once in order to create the output directories, binaries and XML documentation files that you’ll use to configure the SHFB in the next step.

A note about the SHFB configuration file.  The configuration file for the Sandcastle Help File Builder isn’t generated automatically.  You have to create it and specify within it which binaries you wish to be documented.  Unfortunately, this means when you wish to add a new binary or project to the documentation, you will have to edit the SHFB configuration file.  Fortunately, you will be placing this file into source control, so updating it can be done easily by opening it within the IDE as a standard XML file.  Its also pretty easy to understand (one of the reasons why I don’t worry much about the angle bracket tax), so you won’t need to launch the SHFB UI to modify it.  This is the only step in the process that won’t be automated as your project evolves.

So, at this point, you have a build that is ready to be configured for automatically generating your documentation website.  You also now have a full set of binaries and XML documentation files that are within the build directory of your build machine.  You can find them in a subdirectory of the build directory listed on the Build dialog pictured to the right.  In my case, this subdirectory is “[project name]\Release\Binaries\Release”.

Next step is to log onto the build machine to create your configuration file.  I’ll cover this in my next post.