Saturday, November 03, 2007

Integrating Help2 files into VS 2005 - part 1

For various reasons (curiosity among others) I've been playing with integrating custom API documentation into Visual Studio, this turned out to be rather laborious.

For future reference I thought I'd document the process here.

- Create the code to be documented, use xml comments and turn on the generate xml comments switch in the project settings.

- Install Visual Studio SDK (yes, really ...)

- Install Sandcastle

- Install Sandcastle Help File Builder

- Open SHFB and create a Help2 project and customize appropriately.

- When the project builds successfully, open all the various .Hx? files (except .HxS) and remove the DTD reference, and from the .HxC file also the <CompilerOptions> element including contents. (For further info refer to the helpware site.)

- Now Microsoft wants you to use the Help Collection Integration Wizard, or manually edit merge files with Orca, neither of which is any fun.

- WiX has a WixVSExtension that among other thing has <HelpFile>, <HelpFileRef>, <HelpCollection> and <PlugCollectionInto> elements which sound promising.

- The problem: the WixVSExtension is currently broken, specifically bug 1588180 

- The bug comments include a suggested fix that involves recompiling WiX. Due to dependency issues this seems like a PITA.

- There is however also another workaround ... stay tuned!

No comments: