Generate HTML / Help files from VS 2010 C# XML documentation

Horst Walter picture Horst Walter · Jan 24, 2011 · Viewed 25k times · Source

I am looking for a good tool creating HTML / Help files from my VS2010 XML documentation. I have found some commercial tools, such as

I am sure there are more, I just list these two as examples. Also there are simple XSLT stylesheets around to convert the XML to HTML documentation.

What are you using, e.g. is there a free tool to do the conversion, maybe as Add-In. Just to clarify, basically I have found two types of tools:

  1. The ones converting the XML documentation file in different target formats, this is what I am looking for.
  2. Tools helping me to generate the XML documentation in the source code. This is not(!) what I am looking for.

Thanks for your help.


The Sandcastle / SHFB combo works great. Thanks to all who helped.

Some remarks:

  1. NDoc seems to be outdated, last updates are from 2005. That's why I have skipped this.
  2. A similar thread, also very detailed, can be found here: https://stackoverflow.com/questions/3082044/how-to-turn-c-xml-doc-comments-into-something-useful Thanks for the hint!
  3. There are some sources for Sandcastle, the latest version I have found is located here: http://sandcastle.codeplex.com/
  4. In order to generate MsHelp2 I had to install VS 2008 SDK containing hscomp.exe. There is a version 1.0 and 1.1, as far as I could figure it out version 1.0 contains the compiler. See Helixsoft and Social MSDN for some details.
  5. In my case the generated WebHelp does not work correctly with Chrome. It always reloads the index.html page.
  6. The topic here shows how to add namespace infos into sandcastle documentation.
  7. Update as of Nov 2012: For smaller projects I am using Doxygen - I find it a little easier to configure.

Answer

jb_ picture jb_ · Jan 24, 2011

We are using Sandcastle for transformation & Sandcastle Help File Builder as a user interface to manage the help projects. In my opinion the beauty of the Sandcastle and SHFB is, that beside the "average" source code documentation, you can add additional information like architecture of the program, patterns that must be followed or any additional conceptional content for your project that is not tied directly to one class in your program. This can be done by creating additional xml files with the help of the Microsoft Authoring Schema (can be edited with visual studio as the xml file and the schema for it are available). Its pretty easy to start with those both tools to creating MSDN like documentation.

A long time ago I tried docbook which is nearly the same on the technical side (xml files containing the information and xslt files to transform it to various output types). But it was no option for us, because there is no transformation out there that can use the visual studio generated xml documentation (plus the transformation of conceptual content was pretty painful for us).