Auto-generating help with NAnt and CC.net

We are about to be audited here where I work. That is the IT department, not the company as a whole. As part of this we have to get all our IT documentation up to scratch. One problem being we don't know when they are coming and what exactly they are wanting to look at. So as far as we can see we have three areas of documentation:-

1. Procedures - Basic how to's for everyday operations of our IT department

2. User help - This documentation covers basic help files for our end users (our end users are actually fellow employees as all our applications are for in house use only)

3. Code documentation - If we were developing components for use outside our company we would be creating API documentation, as we are not we use XML comments within our applications to explain what classes and methods do.

In getting ready for this audit, one of my tasks has been to get number 3 ticked off. As we have implemented a CI environment, I wanted to get an automated system in place that would generate html help style documentation. I decided to look in to the Sandcastle project and specifically the Sancastle Help File Builder tool.

The Sancastle Help File Builder tool is a fantastic GUI interface to configure and create both HTML Help and web page documentation (I wont' discuss this in depth here). Basically just point it at your .exe or .dll set a few parameters and you are off. Great when you are manually doing it, but for automation; no. Well inside the deployment directory is a command line tool; SandcastleBuilderConsole.exe. Use the GUI tool to create your project and set any parameters and then save it as an .shfb file. Then pass your .shfb file generated to the SandcastleBuilderConsole application and your help file will be created.

Now both the Sandcastle Help File Builder tool and its command line version need the XML comments from your application. Visual Studio will generate this automatically by going to the project properties build tab and selecting the XML documentation file tick box. If however you are wanting NAnt to do it automatically each time you perform a build, add the doc attribute to your csc element like this:-

   1: <csc target="library" output="nant_build\ReportsPdf.dll" 

   2:          doc="nant_build\ReportsPdf.xml">

Then somewhere within your target element, add the command to run the exe which points to your SandCastleBuilderConsole.exe, like this:-

   1: <exec 

   2:       program="C:\Program Files\EWSoftware\Sandcastle Help File Builder\SandcastleBuilderConsole.exe"

   3:       commandline=""${SandCastleDocPath}\${SandCastleHFBProject}""

   4:       failonerror="true"/>

The two properties for the commandline attribute are set earlier on in the NAnt file like so:-

   1: <property name="SandCastleHFBProject" value="sandcastle.shfb"></property>

   2: <property name="SandCastleDocPath" value=".\Sandcastle\"></property>

For some of our projects it can take a while to generate this help file, so you may want to add an extra project to your ccnet.config file which will run at a specified time instead of watching for changes in source control. I have covered these options in this post.

When the help file is produced, at the bottom of each page is the assembly build number. Now this is fine, but if you want to configure the build number to be the same as that which cc.net assigns you need to do a bit more work.

Firstly you need to call the asminfo element in your NAnt script like this before you call csc:-

   1: <asminfo output="Properties\AssemblyInfo.cs" language="CSharp">

   2:     <imports>

   3:       <import namespace="System" />

   4:       <import namespace="System.Reflection" />

   5:     </imports>

   6:     <attributes>

   7:       <attribute type="AssemblyTitleAttribute" value="ReportsPdf" />

   8:       <attribute type="AssemblyCopyrightAttribute" value="Copyright (c) 2008" />

   9:       <attribute type="AssemblyVersionAttribute" value="${CCNetLabel}" />

  10:     </attributes>

  11:   </asminfo>

It is the CCNetLabel which does the magic work. Now in your ccnet.config file you need to add the labeller element inside your project element like this:-

   1: <labeller type="defaultlabeller">

   2:   <prefix>1.0.0.</prefix>

   3:   <incrementOnFailure>False</incrementOnFailure>

   4: </labeller>

Now after performing a build, you will get documentation labelled the same as cc.net and is generated as and when you add your XML comments and check them in to source control.

Now I have the less interesting task of making sure we have all the methods etc documented. Could take some time.