Seamless integration makes for a happy world. You can take all that homegrown documentation and blend it right into the Visual Studio help system.
If you are writing a framework, control, add-in, or anything your users might use directly from Visual Studio, it can be very helpful to integrate your help documents directly into Visual Studio. Using a combination of NDoc, the Visual Studio .NET Integration Kit, and a freely available tool, you can quickly and somewhat easily integrate your documentation directly into Visual Studio.
The first step is to download the Visual Studio .NET Integration Kit. NDoc will use this kit to create your documentation in the HTML Help 2 format, the format used by Visual Studio. The Visual Studio .NET Integration Kit can be downloaded from http://msdn.microsoft.com/library/default.asp?url=/library/en-uslhelpl/hwmscextendingnethelp.asp.
To integrate help documentation into Visual Studio, you have to generate your documentation a little bit differently. Instead of creating your documentation using the MSDN documentation type [Hack #71] , you will need to create VS.NET 2003-type documentation. This is done by simply selecting VS.NET 2003 from NDoc's list of documentation types. (This documentation type is new to NDoc 1.3, so make sure you have the latest copy of NDoc.)
You will also need to make a couple configuration changes. Under the HTML Help 2.0 Deployment section, make sure that GenerateCollectionFile is set to trueyou will also need to specify a CollectionNamespace. The CollectionNamespace should be a unique value similar to your project's namespace. (Don't use a URI, spaces, or special characters though.)
These settings are shown in Figure 8-7.
You will also want to make sure that you set a title for your help documentsthis will be used as the top node when adding your help documents to the Visual Studio help tree. When you build your help, NDoc will do the majority of the work for you. NDoc will not only create HTML help files, but will also create the files needed to register your help files.
The next step in this process is to register your help file. The easiest way to do this is to use a small utility called H2Reg created by the people at . This utility can be downloaded from http://www./mshelp2/h2reg.
The H2Reg utility uses an .ini file to specify what help files to register. NDoc is nice enough to actually generate this .ini file for you, and the file can be found in the same directory where NDoc put your other help files.
Once you have downloaded and installed H2Reg, you will need to run it from the command line using the -r switch and specify the name of your .ini file. Here is an example command that registers a help file:
C:\> h2reg -r CmdFile=C:\HelpDocs\DocumentationCollection.h2reg.ini
The H2Reg utility will then register your help documentation. This process can also easily be integrated into an installation procedure if you want to install this documentation when a user installs your add-in or control. You can include the small H2Reg executable with your installation files and simply call it from your installation and uninstallation programs. To uninstall your help documentation, you simply need to run the same command with -u instead of -r.
You may or may not have to perform this step. Usually the help collection is automatically added to Visual Studio, but if it does not show up, you will need to run the Help Collection Manager and add your help collection. The Help Collection Manager is easy to use and can be accessed by simply navigating to Figure 8-8.
If your help collection (XMLLib in Figure 8-8) is not already checked, you will need to check it and then click the Update VSCC button. Your help collection will now be installed and ready to use in Visual Studio.
You should now see your help documents in Visual Studio. An example of how they appear is shown in Figure 8-9.
Integrating your help documents into Visual Studio can be a great benefit to your usersusing a couple of freely available tools makes it much easier.