Use Sandcastle XML Transforms for Visual Studio Help

Sep 8, 2011 at 4:17 PM

I work on the .NET Gadgeteer project, where we are trying to prototype a methodology that module manufacturers can use to create help files from the triple slash comments in Visual Studio C# files.  The ///<summary/> already builds Intellisense and Object Browser XML when the build uses the documentation switch.  The problem is getting the ///<remarks/> and ///<example/> ///<code/> texts into a form that can be used by Visual Studio help.  Is there a way that we can use Sandcastle transforms to do this?  We want manufacturers building modules to be able follow our implementation when building their own help.

Sep 8, 2011 at 8:06 PM

There's quite a bit more to it than just running the XML comments through some XSL transformations.  The XSL transformations are used in combination with a set of tools in Sandcastle that ultimately produce HTML files that are then compiled into a help file.  That final steps depends on what help file format you want (Help 1 (CHM), Help 2 (HxS), or MS Help Viewer (MSHC)) and thus requires additional tools be installed above and beyond Sandcastle itself.

By themselves, the Sandcastle tools can be rather hard to use since they don't come with any documentation and it provides no means of managing a project beyond a simple example GUI and some sample build scripts.  Third-party front ends for it, like the Sandcastle Help File Builder, can help with that and make it much easier to use and provide additional features.  They also use MSBuild-format project files so building help files becomes much simpler and they can be integrated into the overall build process fairly easily.

Of course, this all assumes that the .NET Gadgeteer projects you want to document result in a managed assembly that the Sandcastle tools can use to create the reflection information that they need to produce the API documentation.  Without that, it won't be of any use unless you can generate the reflection information in some other manner.


Sep 8, 2011 at 8:30 PM

Thanks, Eric,

.NET Gadgeteer modules use managed code and assembly, so in theory what we have in mind should be feasible.  I'll ping the other interested players.

Mike Dodaro