Integrate NDoc HTML Help in VS.NET

By Fons Sonnemans (30 December 2003)

Download NDocSample.zip

Introduction

NDoc 1.2 generates class libraries documentation from .NET assemblies and the XML documentation files generated by the C# compiler. NDoc uses add-on documenters to generate documentation in several different formats, including the MSDN-style HTML Help format (.chm), the Visual Studio .NET Help format (HTML Help 2), and MSDN-online style web pages.

This article explains the four steps to take in order to integrate the HTML Help 2 file you generated into Visual Studio.NET.

  1. Comment the Library using XML documentation tags
  2. Create HTML Help 2 using NDoc
  3. Registering the Help File using H2Reg
  4. Include Help Collection to VSCC

Step 1: Comment the Library using XML documentation tags

I have created a sample library with two classes Employee and EmployeeCollection. These classes are documented using the XML documentation tags (///). The assembly is named ReflectionIT.NDocSample.

using System;

namespace ReflectionIT.NDocSample
{
    /// <summary>
    /// Employee class used to demonstrate NDoc and Visual Studio.NET integration.
    /// </summary>
    /// <example>
    /// Some sample:
    /// <code>
    /// Employee emp = new Employee("Jim", 4000);
    /// emp.RaiseSalary();
    /// Console.WriteLine(emp.GetYearSalary);</code>
    /// </example>
    public class Employee
    {
        private string _name;
        private int _salary;

        /// <summary>
        /// Initializes a new instance of the Employee class with a name and salary.
        /// </summary>
        /// <param name="name">The name of the employee</param>
        /// <param name="salary">The salary of the employee</param>
        public Employee(string name, int salary)
        {
            this.Name = name;
            this.Salary = salary;
        }

        /// <summary>
        /// Gets or sets the name of the employee.
        /// </summary>
        public string Name {
            get { return this._name; }
            set { this._name = value; }
        }

        /// <summary>
        /// Gets or sets the salary of the employee.
        /// </summary>
        public int Salary {
            get { return this._salary; }
            set { this._salary = value; }
        }

        /// <summary>
        /// Returns the year salary for the employee using 12 months
        /// </summary>
        /// <returns>The year salary</returns>
        public virtual int GetYearSalary() {
            return Salary * 12;
        }

        /// <summary>
        /// Raise the salary with 10%
        /// </summary>
        public virtual void RaiseSalary() {
            Salary += Salary * 10 / 100;
        }
    }
}

The assembly is named ReflectionIT.NDocSample. I have set the name of the xml file in which the documentation comments are processed to ReflectionIT.NDocSample.xml. Make sure this is the same name as the assembly otherwise IntelliSense will not work correctly. Don't forget to compile the assembly; this will create the xml file.

Step 2: Create HTML Help 2 using NDoc

NDoc comes with a GUI front end (NDocGUI.exe) and a console application (NDocConsole.exe). I have used the NDocGui to create a NDoc project for my NDocSample library. You can easily do this using the 'New from Visual Studio Solution...' menu option.


Next you have to set the Documentation Type to 'HtmlHelp2'. I have also changed some extra properties like: CopyrightHref, CopyrightText, HtmlHelpName and Title.

Then you are ready to build the help file. Before you can do this you have to install Microsoft Html Workshop and Microsoft Visual Studio .NET Help Integration Kit (VSHIK2003). You build the help file using the Documentation, Build menu option (Ctrl+Shift+B). The result is an ReflectionIT.NDocSample.chm help file which NDoc converted to compiled Html Help.

Step 3: Registering the Help File using H2Reg

I have used H2Reg to register the NDocSample help file. H2Reg.exe is a small utility (177K), that allows you to register MS Help 2.x Collections: Namespaces, Titles, Plug-ins, and Filters without using MSI (Microsoft Installer).

To use H2Ref you have to create an ini file in which you describe what you want to register. Below you see the H2Reg_cmd.ini file I used to register the NDocSample help file.


;------- Register -r switch

[Reg_Namespace]
;<nsName>|<nsColfile>|<nsDesc>
ReflectionIT.NDocSample|ReflectionIT.NDocSample.HxC|ReflectionIT NDocSample

[Reg_Title]
;<nsName>|<TitleID>|<LangId>|<HxS_HelpFile>|<HxI_IndexFile>|<HxQ_QueryFile>|
;<HxR_AttrQueryFile>|<HxsMediaLoc>|<HxqMediaLoc>|<HxrMediaLoc>|<SampleMediaLoc>
ReflectionIT.NDocSample|ReflectionIT.NDocSample|1033|ReflectionIT.NDocSample.HxS|||||||

;------- UnRegister -u switch

[UnReg_Namespace]
;<nsName>
ReflectionIT.NDocSample

[UnReg_Title]
;<nsName>|<TitleID>|<LangId>
ReflectionIT.NDocSample|ReflectionIT.NDocSample|1033


I have placed this ini file together with the ReflectionIT.NDocSample.HxC and ReflectionIT.NDocSample.HxC files into a folder called Help. In this folder you have to start H2Reg with the -R switch which I have automated using the following register.bat batch file.

copy ..\Ndoc\doc\*.hxS
copy ..\Ndoc\doc\*.hxC
"C:\Program Files\Helpware\H2Reg\H2Reg.exe" -r cmdfile="C:\My Documents\Visual Studio Projects\NDocSample\Help\H2Reg_cmd.ini"

Step 4: Include Help Collection to VSCC

The last step is to include the help collection in Visual Studio .NET 2003 Combined Help Collection (VSCC). Therefore you have to open the 'Visual Studio .NET Combined Help Collection Manager' page using the following hyperlink: ms-help://MS.VSCC.2003/VSCCCommon/cm/CollectionManager.htm. In this page you have to select the 'ReflectionIT.NDocSample' checkbox and click the 'Update VSCC' button.


You can change the Title attribute of HelpCollection node in the .HxC file when you want a more descriptive name.

Result

The result off all these steps is great. You will see the help file integrated into Visual Studio.NET. It is context sensitive (F1) and will also appear in the Dynamic Help.



Conclusion

The Xml documentation comments of C# are great. With NDoc and H2Reg you can generate an Html Help 2 file and integrate it in Visual Studio.NET. This will make your code libraries really (re)usable.

I haven't figured out how to add Filters and Contents (TOC). I hope to update this article soon with these options. When you find this all to difficult you should look at DocumentX which is a lot easier to use, but not for free.

Any suggestions and feedback for improving this Add-In is most welcome. Send your suggestions and feedback to Fons.Sonnemans@reflectionit.nl