Building Sandcastle Documentation

Description

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

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 recipe 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.

Edit

Usage

Add to TFSBuild.proj as an override of the GenerateDocumentation target

Edit

Prerequisites

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/

Edit

Source

Grant Holliday's Blog - Building Sandcastle Documentation with Team Build

Edit

Script


<Import  Project="$(MSBuildExtensionsPath)\MSBuildCommunityTasks\MSBuild.Community.Tasks.Targets"/>
 
 <Target Name="GenerateDocumentation">
   
   <CreateItem Include="$(OutDir)*.dll">
     <Output ItemName="Assemblies" TaskParameter="Include" />
   </CreateItem>
 
   
   <CreateItem Include="@(Assemblies)"
               Condition="Exists('%(Assemblies.RelativeDir)%(Assemblies.Filename).xml')">
     <Output ItemName="AssembliesToDocument" TaskParameter="Include" />
   </CreateItem>
 
   
   <CreateItem Include="@(Assemblies)"
             Condition="!Exists('%(Assemblies.RelativeDir)%(Assemblies.Filename).xml')">
     <Output ItemName="DependenciesToDocument" TaskParameter="Include" />
   </CreateItem>
 
   <PropertyGroup>
     <SandcastleBuidlerPath>C:\Program Files\EWSoftware\Sandcastle Help File Builder\SandcastleBuilderConsole.exe</SandcastleBuidlerPath>
 
     
     <SandcastleBuilderProjectTemplateFile>$(MSBuildExtensionsPath)\template.shfb</SandcastleBuilderProjectTemplateFile>
     <SandcastleBuilderProjectFile>$(MSBuildProjectDirectory)\project.shfb</SandcastleBuilderProjectFile>
 
     
     
     
     
 
     
     <SandcastleBuilderArguments>@(AssembliesToDocument -> '-assembly=&quot;%(RelativeDir)%(Filename).dll&quot;',' ') @(DependenciesToDocument -> '-dependency=&quot;%(RelativeDir)%(Filename).dll&quot;',' ') -outputpath=&quot;$(OutDir).&quot;</SandcastleBuilderArguments>
 
   </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>

Edit

Notes

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:

Copy the documentation file to your local machine, right-click, select properties, select Unblock.
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