I wonder if there's any chance of something like this taking off in Sydney. Maybe there's just something so incredibly Japanese about it that it wouldn't work, but I just love the idea.
Either way, it seems Sarah Marchildon has struck a bit of a chord with her blog posting, generating all sorts of interest.
Perhaps I should buy a fancy espresso machine and add a dozen cats to the household, and set myself up as the Sydney branch of 猫の時間 (Neko no Jikan, or "Cat Time").
Oh well, so much for my earlier optimism - it turns out, that for the time being at least, Sandcastle can't easily be used on a build server.
The problem is the Help 2.0 Compiler, which in a previous life as the Help 1.x Compiler, was shipped as a standalone product. However, Microsoft, in its infinite wisdom, decided to bundle the 2.0 version into the Visual Studio SDK; and of course, to install the Visual Studio SDK, you need to first have an installation of Visual Studio, which rather defies the point of a build server. Especially for small operations on a budget, having to acquire an extra VS license just to automate the creation of documentation is more than a pain in the neck, it's downright unsociable.
There are some guides on working round this, but they only cover up to VS2005 and its SDK, whereas we're using VS2008 SP1.
I'm going to have a play around with exporting chunks of my registry which has references to the 2.0 compiler, in the hope that that fixes things. I don't hold out much hope.
It's been a while since my last release of SvnRevisionLabeller, and I've not paid the project pages too much attention, seeing as everything was very quiet. Unfortunately, I hadn't set up the project to notify me whenever issues were raised, so I'd missed the raising of several bug or change requests.
Well, after stumbling upon one such change request during an unrelated Google session, I thought I'd better catch up on my project maintenance; it doesn't look very professional when your projects have bug reports unloved, unacknowledged, and unresolved.
The biggest change is that build number will be configurable; it was one of the first feature requests, and for a current project at work, it's something I wanted to do anyway.
BTW if you have downloaded and installed the plugin, I'd be interested to know. Google reports 822 downloads; the person who filed that request has linked to their site, so that's one, and of course I use it at Fairfax Digital, so that's two. Anyone care to offer up any of the other 820 downloads?!
For a new project at work, I'm adding automatically-generated API documentation as part of my nightly build. Back in the days of .NET 1.1, we had the NDoc project, and explicit support for it in NAnt. Unfortunately, the project never made the transition to .NET 2.0, instead coming to a rather bitter and public end due to predominantly a lack of community support (despite the large numbers of downloads). I guess it's one the main failing of open-source projects - many are happy to take, but not so happy to give (whether money or time/effort).
Sandcastle is Microsoft's official documentation generator, but even three years on, it lacks some of the user-friendliness that any NDoc user had come to expect. The Sandcastle Help File Builder tool goes a long way to rectifying this, but most of the focus is on the GUI tool. Until the current v1.8 release, command line builds were taken care of by the SandcastleBuilderConsole.exe tool; however, the latest release drops this, and instead uses MSBuild, which ships with the .NET Framework. This is a rather nice touch, in my opinion - a clever use of existing tooling, rather than writing another new tool.
However, the documentation about using it in a continuous integration environment is still a little lacking, so I'm documenting here the problems I came up against.
So far, it seems like neither Sandcastle nor SHFB have been designed with easy deployment in mind. I like to include my build tools within my source repository; this saves a lot of tedious installation and configuration whenever setting up a new developer PC. Both tools come as MSI packages, with Sandcastle deploying as a 220Mb install, so maybe that one you can do without in your repository! SHFB on the other hand is relatively lightweight, at around 3Mb for the files required by the build tasks. You will need to set an environment variable for it to run properly, though:
<setenv name="SHFBROOT" value="${Sandcastle.dir}" unless="${environment::variable-exists('SHFBROOT')}" verbose="true" />
The SHFB files that you seem to require are:
You'll also need the Help 2.0 Compiler tool hxcomp.exe, which ships as part of Visual Studio 2008 SDK; and of course, the SDK requires that Visual Studio 2008 is installed before it itself will install. Fortunately, you can pull out the contents of C:\Program Files\Common Files\Microsoft Shared\Help 2.0 Compiler\ and add that to your repository as well, bypassing that little pain-in-the-neck.
To use SHFB within CC.NET with NAnt, you'll need the <msbuild> task that comes with NAntContrib. The syntax is as follows:
<msbuild project="${source.basedir}\Documentation.shfbproj"> <arg value="/property:${HxComp.dir}" /> <arg value="/property:SandcastlePath=C:\Program%20Files\Sandcastle\" /> </msbuild>
All the properties listed in the SHFB GUI tool can be set as above - just watch out for the need to escape spaces when hard-coding paths, which had me stumbled for an hour or two, until I found a post asking the same question.
The one thing I really want to get done is programatically set the assemblies which will be documented; at the moment, you either use the GUI tool and relative paths, or edit the SHFB project file by hand. You could probably also use NAnt's <xmlpoke /> task to edit it, but I would prefer to be able to set it via parameters to the <msbuild /> task, so watch this space while I work it out.
