لطفا منتظر باشید ...
Hack 72. Integrate Your Own Documentation into Visual Studio
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-us/htmlhelp/html/hwmscextendingnethelp.asp.
8.6.1. Create Documentation with NDoc
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.
Figure 8-7. NDoc HTML help options
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.
8.6.2. Registering Your Help File
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.
8.6.3. Include Your Help Collection
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.
Figure 8-8. Help Collection Manager
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.
Figure 8-9. Integrated help
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.
