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=”"$(SandCastleExePath)" @"$(SandCastleResponseFile)" -workingpath="$(SandCastleWorkingDir)" -outputPath="$(SandCastleOuputLocation)"” /> <!– Clean working directory –> <RemoveDir Directories=”$(SandCastleWorkingDir)” /> </Target>