Sandcastle is a tool from Microsoft to generate documentation as help files from the XML comments in your c# (or vb.net) code.
The latest version is the September 2007 CTP, announced here: http://blogs.msdn.com/sandcastle/archive/2007/10/02/announcing-september-2007-sandcastle-release.aspx
Sandcastle has a reputation as being not release quality yet/ difficult to work with.
Some of that is deserved.
We wanted to get this working as part of the automated build using a TFS build server. Initially this looked daunting, but after some toil and false starts, here is an easy way to get sandcastle documentation generated from your solution without to much pain.
The steps are:
First, get it working on your developement machine:
* Comment your code with XML comments
* In all projects in your solution, Generate xml documentation file output. Right-click the project, bring up the properties tab, click on the build tab, check the box labeled "XML documentation file". At this stage we got warnings (as errors, of course) for all public classes and methods that didn't have XML comments. So we added them at this stage.
* If you don’t already have it, install html help workshop from http://msdn2.microsoft.com/en-us/library/ms669985.aspx – you need the "hhc.exe" help compiler.
* Install the Sandcastle September 2007 CTP from the link given above.
* Install the Sandcastle help file builder from http://www.codeplex.com/SHFB
* Patch sandcastle with "Sandcastle Presentation File Patches" also in SHFB's downloads section.
* Run the SHFB executable and make a shfb project from the solution. See the SHFB help file for details.
* Make sure that the path to the help compiler is explicitly specified in the SHFB project. This is needed for the commandline build that will happen on the build server
* build the SHFB project, inspect the output.
* add the SHFB project to your solution, as in the SHFB help file. Check it into TFS
Now move over to the build server and incorporate it into the TFS Buils:
*Install all the software mentioned above on your build machine.
* Add a target to the TfsBuild.proj file to build the SHFB file. Ours looks like this:
<Target Name="PackageBinaries" DependsOnTargets="SandcastleDocs">
<Message Text="PackageBinaries target executed." />
<!-- Build source code docs -->
<Exec Command=""C:\Program Files\EWSoftware\Sandcastle Help File Builder\SandcastleBuilderConsole.exe" "$(SolutionRoot)\main\Solutions\path\To\Docs\Project Documentation.shfb"" />
"$(SolutionRoot)\path\to\to\file\Project.Documentation.shfb" is where the .shfb file is located when it is gotten onto the build server.
The problem at this stage is that a TFS build server keeps binaries in a different location to a local build. While in a local build, the binaries can be found in <projectname>\bin\Debug, but on the TFS build server they are located for all projects in ...\Binaries. The only solution that we have for this is to edit the .shfb file to work on the build server (and only on the build server).
Ours now reads in part:
<assembly assemblyPath="..\..\..\..\..\..\Binaries\Debug\Assembly1.dll" xmlCommentsPath="..\..\..\..\..\..\Binaries\Debug\Assembly1.XML" commentsOnly="False" />
<assembly assemblyPath="..\..\..\..\..\..\Binaries\Debug\ Assembly2.dll" xmlCommentsPath="..\..\..\..\..\..\Binaries\Debug\Assembly2.XML" commentsOnly="False" />
If all goes well, check this in and build and it should produce docs in .chm format on the build server.
* To copy the .chms to the output directory, you can add a copy command to the SandcastleDocs target:
<HelpFiles Include="$(SolutionRoot)\main\Solutions\Path\To\Docs\Help\*.chm" />
<Exec Command=""C:\Program Files\EWSoftware\Sandcastle Help File Builder\SandcastleBuilderConsole.exe" "$(SolutionRoot)\main\Solutions\Path\To\Docs\Project Documentation.shfb"" />
<Copy SourceFiles="@(HelpFiles)" DestinationFolder="$(BinariesRoot)\Debug" />
And that's the easy way. You should see the hard way!
Update: see part 2 and part 3