Sunday, March 09, 2008

Continuous Documentation cont...

As it usually happens, after going through all the troubles to have a continuous documentation happening (see previous post) in my project I found out a much easier way to achieve the same. While the previous post concentrated on purely using the native sandcastle xsl files to apply several xml/xsl transforms using Nant, the new easier method will rely on the very useful tool 'Sandcastle Help File Builder' or SHFB as it's also known. You need to download and install SHFB in both your local machine and the build machine. ( It would be better to breeze through my previous post before you go through this)

Let me run through the simple steps involved in this method.
1. Open up SHFB in your local machine and configure it to generate the documentation to your project.
2. Some important steps in configuring the SHFB are,
  • Adding the assembly and the documentation xml (Generated from the Nant -doc attribute as mentioned int he previous post) for documentation
  • Adding the dependent assemblies needed to build the main assembly
  • Choose the helpfile format (I choose Help2xAndWebSite)
  • Set HtmlHelp2xCompiler Path (Where you have installed HTML Help Workshop, see previous post)
  • Set output path
3. Build the SHFB project and let the documentation to generate
Now you will have the documentation files (html, chm) in your local machine, which is not our target. We want the documentation to build periodically, automatically in our build machine. Patience....2 more steps.
4. Now save your SHFB project and you will find a SHFB configuration file. Get it copied to your build machine.
5. Now include the following task tag in to your ccnet documentation project (other project tags are not mentioned here) and you are ALL SET to have continuous documentation running in your project.

<tasks> <exec> <executable>C:Program FilesEWSoftwareSandcastle Help File BuilderSandcastleBuilderConsole.exe</executable> <baseDirectory>D:WorkDirSandcastleWorkDirSPNPortalDocumentation</baseDirectory> <buildArgs>"D:WorkDirSandcastleWorkDirSPNPortalDocumentationDocumentationSettings.shfb"</buildArgs> <buildTimeoutSeconds>10800</buildTimeoutSeconds> </exec>

</tasks>

Pay attention to the 'buildArgs' element where you specify where the shfb configuration file can be found.
Post a Comment