Friday, 9 October 2009

Build MSDN Help with FinalBuilder and Sandcastle

We are using FinalBuilder as continuous integration platform developing our in-house application framework. Documentation was built with Sandcastle. A Sandcastle Help File Builder project was executed in FinalBuilder as "Run DOC Command / Batch File" action with specific parameters defining build options.
But that was not very nice in regard to that FinalBuilder has specially designed actions to support Sandcastle, BuildAssembler, MRefBuilder, XslTransform:




So far so good, but believe me, that is not what you want. First you have to know how Sandcastle ticks internally, what xslt transformations are necessary for what help types and so on. Secondly, the whole procedure is complex and very error prone. There several xslt transformations are necessary to achieve the desired result. Take a look at this tutorial and you'll know what I mean.
Recently I discovered that GUI client for Sandcastle, which is Sandcastle Help File Builder, also available on the Codeplex, moved to a standard MSBuild format project file. That means to us developers, we can use it in a standard MSBuild action provided in the FinalBuilder. The benefits are obvious:
  • you can use Sandcastle Help File Builder to define and manage your project



  • use only one action to build your MSDN 1 or 2 or HTML help



  • easily forward FinalBuilder properties like help file format or output path to SCHB


I'm not eager to tell here how I'm impressed by the FinalBuilder. Being long time a devoted user of Ant, now I know what a build tool must look like. It's very comfortable to handle, has plenty of actions for almost every imaginable developer task and if not enables you to extend it with your own actions and it just works as it should.
The only drawback of building help in the FinalBuilder, it takes much longer then to get the project built directly in the SCHB, but on the other hand you get a couple more minutes for a cup of good coffee.

No comments: