Hi folks,
a few days ago I figured out how to create HTML help files from code comments and how
to integrate them into visual studio so pressing F1 on one of my classes opens the
generated help file.
Because I spent much time googleing the world getting all information I needed I decided
to write down how I did it:

1. Download and install tools

- Sandcatle

- Sandcastle Help File Builder

- HTML Help 2.0 compiler
The Help 2.0 compiler is integrated into the VS SDK (VS2005) (VC2008)

The compiler will be installed in the directory “%Program Files%\Common Files\Microsoft Shared\Help 2.0 Compiler\”.
Search for hxcomp.exe if you can’t locate it.

2. Configure Visual Studio to generate XML comment file

Open Project properties. Select Build tab and ensure that the checkbox “XML documentation file” is checked.
Then recompile your project.

3. Configure Sandcastle Help Builder

Create a new project and add your assembly to the project. Ensure that an xml file was found too. The added
entry should look like “MyAssembly.dll, MyAssembly.xml” and not like “MyAssembly.dll, Unknown.xml”. In this case
your xml documentation file was not found and a documentation cannot be build.

Lets go on with the settings:

Build > Help File Format: Enable HtmlHelp2x
Build > Dependencies: Add all assemblies your assembly depends on here.
Build > Framework Version: Select the .NET Framework version your assembly is build on.
Help File > Presentation Style: Select vs2005. This is not neccessary but pretty.
Paths > HtmlHelp2xCompilerPath: Give the path to the directory where hxcomp.exe is located.
Paths > SandcastpePath: Set it to the correct installed sandcastle path. In my case I had multiple versions
of sandcastle installed and had to specify where the newest version is installed.

4. Build help file

Now you should be able to build your help file. You cannot view Help 2 files without special viewers.
So build HTML Help 1.x files first until your output fits your needs. Play around with the
settings and define style, disable warning and define what you want to be documented.
Finally build a HTML help 2.0 file if your want to get it integrated into the Visual Studio
help system and go on with the next step.

5. Integrate help file into Visual Studio

Run Visual Studio.
Select File > New Project.
Select Other Project Types > Extensibility > Help Integration Wizard
In the first assistant step leave “Setup project” selected, chose your Visual Studio version and go next.
In the second assistant step add your Html Help 2 files (*.hxs).
Configure the last two steps as you wish.
Build the project.
Run the created setup which installes your help files into visual studio.

That’s it! Happy Easter!

Alexander

kick it on DotNetKicks.com

Post to Twitter Tweet this