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!
_1098.png){kind=small}
No comments:
Post a Comment