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.*.xmlAnd here is how to call Sandcastle in MsBuild with the use of the response file:
-dependency=Microsoft.Practices*
-dependency=System.Dependency*
-VisibleItems="InheritedMembers, InheritedFrameworkMembers, Protected, SealedProtected"
-ShowMissingParams=true
-ShowMissingRemarks=false
-ShowMissingReturns=true
<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=""$(SandCastleExePath)" @"$(SandCastleResponseFile)" -workingpath="$(SandCastleWorkingDir)" -outputPath="$(SandCastleOuputLocation)"" />
<!-- Clean working directory -->
<RemoveDir Directories="$(SandCastleWorkingDir)" />
</Target>
If you liked this post ... here's more for you:
Published by on Last updated