Calling Sandcastle with response file

Posted by Marcus Hammarberg on November 17, 2008
Stats
I've been generating documentation from our XML-comments with Sandcastle for quite some time now. It has worked alright but there were some stuff that really annoyed me, I though that I had to put up with it.
But this is the beauty of my line of work comes into play... all of a sudden we've got a new team member. Christer Cederborg from Avega (of course) - a great guy and very knowledgeable in things like build scripts and other. And you get to learn from each other. This is why I am in this business - sharing and knowing.
OK - Christer told me that you can use something called a response file to send commands to Sandcastle. The response file is in fact just the parameters you would send to Sandcastle the command line, but in a file. This made us go around the use of .shfb-files.
Sandcastle Help File Builder is certainly a great tool when you generate the documentation manually but is sucks when it comes to incorporating it into a build script. You cannot use wildcards or relative paths in .shfb-files which complicate things in a major way. I actually created two separate file, one for local developer use and one for our build script. They were of course almost always out of sync...
But with the use of a response file you can set all the commands you need to Sandcastle and get the same result. Here is a short extract from our response file:
-assembly=SystemName.*.dll, SystemName.*.xml
-dependency=Microsoft.Practices*
-dependency=System.Dependency*
-VisibleItems="InheritedMembers, InheritedFrameworkMembers, Protected, SealedProtected"
-ShowMissingParams=true
-ShowMissingRemarks=false
-ShowMissingReturns=true
And here is how to call Sandcastle in MsBuild with the use of the response file:
<PropertyGroup>
<!-- Sandcastle parameters -->
      <SandCastleExePath>C:\Program Files\EWSoftware\Sandcastle Help File Builder\SandcastleBuilderConsole.exe</SandCastleExePath>
        <SandCastleOuputLocation>$(DropLocation)\SystemDokumentation\Tjanster</SandCastleOuputLocation>
        <SandCastleWorkingDir>$(CurrentSolutionRoot)\SandCastleWorkingDir</SandCastleWorkingDir>
        <SandCastleResponseFile>$(CurrentSolutionRoot)\Solution Items\Documentation\SystemName.SandCastleSettings.txt</SandCastleResponseFile>
</PropertyGroup>

<Target Name="GenerateDocumentation" Condition="'$(Documentation)' == 'true'">
    <!-- Clean directories -->
    <RemoveDir Directories="$(SandCastleOuputLocation)" />
    <MakeDir Directories="$(SandCastleOuputLocation)" />
    <RemoveDir Directories="$(SandCastleWorkingDir)" />
    <MakeDir Directories="$(SandCastleWorkingDir)" />
    <!-- Create the documentation with call to Sandcastle with the parameters of the response-file -->
    <Exec WorkingDirectory="$(OutDir)"
Command="&quot;$(SandCastleExePath)&quot; @&quot;$(SandCastleResponseFile)&quot; -workingpath=&quot;$(SandCastleWorkingDir)&quot; -outputPath=&quot;$(SandCastleOuputLocation)&quot;" />
    <!-- Clean working directory -->
    <RemoveDir Directories="$(SandCastleWorkingDir)" />
</Target>


Published by Marcus Hammarberg on Last updated