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

(This is part two in a three part series.  You should read the introduction or part one if you haven’t already before reading this post)
By this point, you should have a Team Build created that you’ll be using to create your documentation website.  You should also have run this build at least once so that all your binaries and documentation files are on your build machine.  You’ll need to do this in order to create your SHFB (Sandcastle Help File Builder) configuration file.  If you haven’t done this, then go ahead and build it now.  In fact, you should probably build it to make sure you have the latest binaries available.

Go ahead and log onto the build machine.  I have to RDP (Terminals rocks, but the latest release sucks) in as my build machine is different than my dev box.  Browse to the build directory.  Note, this is not the same as the drop folder.  Documentation is created as a post-build step within the build folder, not within the drop folder.  Make sure all your DLLs, executables and their XML documentation files are there.
Go ahead and run the Sandcastle Help File Builder GUI.  The first step is to add all the binaries and XML comment files you want included in the documentation website.  Click the Add button next to the Assemblies to Document list and browse to the build folder.  Multi-select these files and click Open.

If you haven’t noticed yet, there are lots of options for you to play with within the SHFB UI.  My suggestion is to leave them alone, save for just a few.  The reason is because this is still in beta, and some of the options will cause the website generation to fail.  When I originally began investigating this process, I was able to get it to work fine.  After I changed some of the settings, it began throwing exceptions during the generation process that would kill the entire build.  I strongly suggest that you only change the following settings:

  • HelpFileFormat (set it to website)
  • CopyrightText
  • FeedbackEMailAddress
  • FooterText
  • HeaderText
  • HelpTitle
  • ShowFeedbackControl
  • OutputPath
  • SandcastlePath
  • WorkingPath

You should set CopyrightText, FeedbackEMailAddress, FooterText, HeaderText and HelpTitle to appropriate values.  If you want to show the feedback email address, set ShowFeedbackControl to true.

OutputPath is the path where all HTML files are to be copied.  This should be mapped to a virtual directory within the website you want to host your documentation.  IMPORTANT!  You must give the user account executing the build full control over this directory.  For me, the build is controlled by a domain user account:  TFS Service.  This account has full rights to the destination directory.  Also, in my case, the the web server is on a different machine.  I made virtual directory for the documentation website accessible via a network share in order to be able to “drop” the completed website from the build machine.  IMPORTANT:  SHFB will NOT allow you to set OutputPath to the root of a network share.  This is because SHFB will delete the root directory of the output path before copying its files.  This is to save you from deleting all your website content by accident, I suppose.  Consequently, if you wish to output to a network share, point to a subdirectory within that share.  For example, if your share is \\webserver\docs, set the output to \\webserver\docs\latest or something similar.

It should also go without saying that you must configure security both for accessing the network share and accessing the underlying file system for the user account that will be running your build.  In my case, I had to RDP into my web server box, create the directory where I wanted to store the documentation website, set the permissions on the directory to give TFS Service (my build service’s domain user account) full control.  I then had to configure the directory as a network share, and give TFS Service full control within the permissions for the network share.  This is a two step process that must be done, otherwise SHFB will fail when trying to create, clear or copy files to the share.  If you don’t have experience doing this, I highly suggest you learn the ins and outs of configuring network shares at MSDN or TechNet.

Another thing to keep in mind is that SHFB needs a working path to store files temporarily while processing your documentation.  It defaults to a temporary directory under the OutputPath.
If your OutputPath points to a network share, like mine, you will want to create a local directory for temporary work in order to speed up the process by removing network latency issues.  Again, make sure the build user account has full access to this directory and can create and destroy it at will.

Now that SHFB is configured you need to save your configuration file in the same directory as all your binaries.  We’ll get into why in the next part of this series.  Go ahead and save the file and exit SHFB.  Open up the save file in Notepad (its extension is SHFB , so it isn’t hard to find.  You will see at the top of the file a list of your assemblies and XML documentation files.  You will also notice the path is hard-coded.  You will have to remove all path information, substituting it for the relative path “.\”.  This is because the path may change during the build process.  I didn’t test it both ways, but better safe than sorry.
Once you’ve removed path information, go ahead and save the file.  Now we’re going to test the configuration to make sure everything goes smoothly.  Within the build process, the console version of SHFB will be executed passing in the path to the configuration file.  In order to make this a valid test, make sure your current user account has the exact same rights as the build service user account in the working and output directories.  Go ahead and open a command window on the build machine and run the following (including quotes):

“C:\Program Files\EWSoftware\Sandcastle Help File Builder\SandcastleBuilderConsole.exe” “[full path to the SHFB configuration file]“

Insert the path to the configuration file where it says.  SHFB should kick off and create the website.  If anything goes wrong, you can check the .log file in the output directory for hints as to what happened.  If you have tons of HTML files in the output folder and no exceptions, then you’ve successfully built your help website!

Next, we need to set up the website so you can view your help online as soon as its created.