Now, create a SHFB configuration file for your solution. Make sure you include the necessary libraries and XML comment files. Also, try building the configuration file you just created. It often occurs you need to add a link to another assembly in your configuration too. If that assembly does not have any XML comments, you can use this one: Unknown.XML (right-click, Save As...).
Use the "Namespaces" button on the top-right of the SHFB screen to include/exclude specific namespaces (useful for external assemblies!), and to provide a short description of those namespaces for use in the help file.
In my case, I added this file (and Unknown.XML) to a SourceSafe repository, which will be used by ccnet to always fetch the latest documentation configuration file.
One thing to keep in mind: references to assemblies that should be documented, must be located from the build server's perspective! This means that when your build folder is C:\builds\, your assembly paths must resolve to that location somehow (relative or absolute).
If you are using ccnet as your build server, the following steps are required to add a documentation build to your build server!
Locate your ccnet.config file, and add a new project:
<!-- ... Fetch Documentation.shfb here! ... -->
<scheduleTrigger time="21:00" buildCondition="ForceBuild">
<executable>C:\Program Files\EWSoftware\Sandcastle Help File Builder\SandcastleBuilderConsole.exe</executable>
<buildTimeoutSeconds>10800</buildTimeoutSeconds> <!-- 3 hours -->
<buildArgs>"C:\SandCastle_Documentation\Generated" "C:\Inetpub\wwwroot\SandCastle_Documentation" /E /Q /H /R /Y</buildArgs>
<buildTimeoutSeconds>3600</buildTimeoutSeconds> <!-- 1 hour -->
<xmllogger logDir="c:\Program Files\CruiseControl.NET\Log" />
There are two notheworthy steps here, located inside the <tasks> element. The first task you see there is used to call the SHFB command line tool and instruct it to generate documentation. Now since I want to create a MSDN-style documentation website, I added a second step, copying the deliverables to a folder in my wwwroot. For both steps, make sure you extend the default <buildTimeoutSeconds>! Over here, the thing takes a hour and a half to complete both steps, you see I have configured a larger amount of time there...
Finished? Restart the CruiseControl.NET system service, and you are ready to build SandCastle documentation automatically!
If you are using VSTS Team Build as your build server, the following steps are required to add a documentation build to your build server!
Locate your TFSbuild.proj file, check it out, and add a build target at the end of the file:
<Exec Command=""C:\Program Files\EWSoftware\Sandcastle Help File Builder\SandcastleBuilderConsole.exe" "C:\SandCastle_Documentation\Documentation.shfb"" />
<Exec Command="xcopy "C:\SandCastle_Documentation\Generated" "C:\Inetpub\wwwroot\SandCastle_Documentation" /E /Q /H /R /Y" />
There is one notheworthy step here: the first target task you see is used to call the SHFB command line tool and instruct it to generate documentation. Now since I want to create a MSDN-style documentation website, I added a second task, copying the deliverables to a folder in my wwwroot.
Check-in the build file, and build the solution! SandCastle documentation will now be integrated in your build process.
This is an imported post. It was imported from my old blog using an automated tool and may contain formatting errors and/or broken images.