Grant Holliday

This post outlines how to configure Team Build, Sandcastle and the Sandcastle Help File Builder (SHFB) to generate MSDN-style documentation for assemblies.

Sandcastle produces accurate, MSDN style, comprehensive documentation by reflecting over the source assemblies and optionally integrating XML Documentation Comments. It is command line based and has no GUI front-end, project management features, or an automated build process like those that you can find in NDoc.

Sandcastle Help File Builder is a frontend for Sandcastle that provides graphical and command line based tools to build a help file in an automated fashion.

How it works

The usual way to configure SHFB is to open the GUI and create a SHFB project file from your solution file with your desired configuration. Then you’re supposed to check this file into source control and maintain it each time you add a new assembly.

This post outlines a possibly simpler approach – it uses a common SHFB project template file and passes the assemblies that Team Build generates as arguments to the SandcastleBuilderConsole.exe program. This means it automatically includes all assemblies that have been built.

Once the documentation has been built, it is copied to the Team Build drop location along with the binaries.

Setup: TFSBuild.proj

To actually get Team Build to generate the documentation, we need override the GenerateDocumentation target and insert our new target into the project.

In source control, checkout the TFSBuild.proj file for your build definition and insert the following snippet at the end, just before the </Project> tag.

<Import  Project="$(MSBuildExtensionsPath)\MSBuildCommunityTasks\MSBuild.Community.Tasks.Targets"/>


<Target Name="GenerateDocumentation">

  <PropertyGroup>

    <SandcastleBuidlerPath>C:\Program Files\EWSoftware\Sandcastle Help File Builder\SandcastleBuilderConsole.exe</SandcastleBuidlerPath>

    <SandcastleBuilderProjectTemplateFile>$(MSBuildExtensionsPath)\template.shfb</SandcastleBuilderProjectTemplateFile>

    <SandcastleBuilderProjectFile>$(MSBuildProjectDirectory)\project.shfb</SandcastleBuilderProjectFile>

    <SandcastleBuilderArguments>-assembly=&quot;$(OutDir)*.dll&quot; -outputpath=&quot;$(OutDir).&quot;</SandcastleBuilderArguments>

    <!-- -dependency=&quot;$(SolutionRoot)\References\*.dll&quot; -->

    <!-- HACK: For some reason the -outputpath argument requires a '.' on the end,

     otherwise you get BUILD FAILED: Illegal characters in path. -->

  </PropertyGroup>

 

  <Error Text="Sandcastle Help File Builder is not found at $(SandcastleBuidlerPath)." Condition="!Exists('$(SandcastleBuidlerPath)')"  />

  <Error Text="Sandcastle Help File Builder project template is not found at $(SandcastleBuilderProjectTemplateFile)."

         Condition="!Exists('$(SandcastleBuilderProjectTemplateFile)')" />

 

  <Copy SourceFiles="$(SandcastleBuilderProjectTemplateFile)" DestinationFiles="$(SandcastleBuilderProjectFile)" />

 

  <XmlUpdate XPath="/project/HelpTitle" XmlFileName="$(SandcastleBuilderProjectFile)" Value="Documentation for $(BuildDefinition)" />

  <XmlUpdate XPath="/project/HtmlHelpName" XmlFileName="$(SandcastleBuilderProjectFile)" Value="$(BuildDefinition)" />

  <XmlUpdate XPath="/project/FooterText" XmlFileName="$(SandcastleBuilderProjectFile)" Value="Build Number: $(BuildNumber)" />

 

  <Exec Command="&quot;$(SandcastleBuidlerPath)&quot; &quot;$(SandcastleBuilderProjectFile)&quot; $(SandcastleBuilderArguments)" />

 

</Target>

Configuration

Build Server Setup

The following pre-requisite software is required for the build server:

• Sandcastle Jan 2008 Release from Sandcastle project on Codeplex
• Sandcastle Help File Builder Installer from SHFB project on Codeplex
• Html Help Workshop from Microsoft HTML Help Downloads
• MSBuild Community Tasks MSI from http://msbuildtasks.tigris.org/

Blocked CHM Help Files from a Network Share

Because the drop location is a network share, the viewing of CHM files is often blocked. This is because network shares fall into the “Intranet” security zone, which isn’t trusted.

There are two options for getting around this:

1. Copy the documentation file to your local machine, right-click, select properties, select Unblock.
2. Or disable blocking for the Intranet zone by creating the following registry key. (More information here)

Windows Registry Editor Version 5.00

[HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\HTMLHelp\1.x\ItssRestrictions]
"MaxAllowedZone"=dword:00000001

TODO

• It may be necessary to cater for References or Dependent assemblies. This would be possibly via another command line argument and a <CreateItem> task to search $(SolutionRoot)\References\**\*.dll
• Namespace documentation is usually configured via the SHFB project file, I haven’t covered this in this implementation.

More Information

• Sandcastle team blog
• Sandcastle on MSDN
• Sandcastle project on Codeplex
• Sandcastle Help File Builder project on Codeplex
• MSBuild Community Tasks (there is a documentation file in the download that describes all the tasks and syntax)
• MSDN: Customizable Team Foundation Build Targets
• Microsoft HTML Help Downloads