How To Build Compiled Help With DocProject


The following steps apply to building compiled help for both DocProjects and DocSites:
  1. Open Visual Studio and load a solution that contains a DocProject or DocSite. If you would like to create a new one instead, see Creating a DocProject for a new solution or Creating a DocSite (Quick Start).
  2. Configure DocProject using the DocProject Properties window or the DocProject External UI, the latter being the only option for Express users. For more information, see How To Configure DocProject.
  3. Build the DocProject or DocSite as you would normally build a project in Visual Studio: either stand-alone by building only the project or as part of a solution build. You may also build a DocProject or DocSite on the command-line using MSBuild. For more information, see How To Build Compiled Help With MSBuild.
  4. When building in Visual Studio or the External UI, the Include Project Output Dialog will be shown after the build. Choose the output that you want to include as project items. (See below for more information.)
Note: Building a DocProject or DocSite may cause certain project items to be replaced. For instance, the Sandcastle build engine will remove the four Html Help Workshop files from the project before it begins to build their replacements. For more information, see Build Process.

Build Steps

The build process uses a set of predefined steps that are provided by the particular build engine used by your DocProject or DocSite.

Open Visual Studio's Output window to view the progress while compiled help is being built for your DocProject or DocSite. Build step errors are added to Visual Studio's Error List, which is automatically shown when a help build fails with one or more errors. For certain build steps, warnings are also added to Visual Studio's error list.

If you do not see any build information in the output window then you must change the following setting to Normal or higher: Tools > Options > Projects and Solutions > Build and Run > MSBuild project build output verbosity.

Sandcastle Build Steps

The build steps that are used vary depending upon the current project settings.

Compiled Help
If included, Help 1.x is always compiled before Help 2.x. If no compiled help is configured to be built then Help 1.x HTML output is produced by Sandcastle without compiling a .chm file.

DocSites require Help 1.x HTML files, which are configured to use local framework reference links instead of index links, by default. The sandcastle.help1x.config file controls this setting. If Help 1.x is not configured then it will be built anyway so that the DocSite functions properly; although, a .chm file is not compiled unless the project is configured to do so.

Conceptual and Auto-Generated Reference Documentation
DocProject requires at least one conceptual topic or at least one source (project reference or external) in order to build documentation. Conceptual documentation is always built before auto-generated reference documentation. If both are built, they are automatically merged together to form one physical documentation set.

If a topics.xml file exists in the project's Help\Settings folder and it contains at least one conceptual topic then conceptual documentation will be built. Use the Topic Explorer tool window to add new conceptual topics to the project and to manage the table of contents (TOC). For more information about Topic Explorer, see How To Use The Topic Management Dialog.

Build Items

Build items are special files or folders that are important to a particular build engine, such as Sandcastle. They are specified by the build engine and DocProject uses them in various aspects of the build process, such as determining whether project output must be rebuilt, what kind of build is required (e.g., partial or full), for verifying input and output, and for making build output visible in Solution Explorer.

For more information, see Build Process, Build Items.

Include Project Output Dialog

In Visual Studio Standard edition or higher and the DocProject External UI, the Include Project Output Dialog will be shown after the build has completed, asking if you want to include one of the output files as a project item in your DocProject or DocSite. For each item you may choose to either include the item or not, with the option of applying your choice to the remaining files or configuring that particular DocProject or DocSite to never ask you this again.

In some cases you'll want to just check Apply To All and then click Yes. In certain circumstances, however, you may not want to include one or more project items. For example, the Html directory that is created by the Sandcastle build engine, when it's very large, may be excluded from a DocProject since it doesn't have any use for the HTML files, unlike a DocSite. In that case you must review each item, one at a time, and choose the appropriate action without checking Apply To All or Don't ask me this again.

If your project is under source control, you may want to check Don't ask me this again and click No. To view the build output you must then use the Show all files command in Solution Explorer's toolbar.
General Build Items
The following project items apply to all build engines:

File Name Description
AppData\DocSiteContents.xml DocSite table of contents data file (does not apply to DocProjects_)
AppData\DocSiteIndex.xml DocSite index data file (does not apply to DocProjects_)

Sandcastle Build Items
A total of 14 files and 2 folders may be offered for inclusion as project items by the Sandcastle build engine; however, you are only prompted to include files for the versions of compiled help that the project has built:

File Name Help Version Description
{Project output dir}\{Project Name}.chm 1.x Compiled help file
{Project output dir}\{Project Name}.HxS 2.x Compiled help file
Help\Html\ 1.x Directory that contains the HTML files generated by Sandcastle for help 1.x only.
Help\Html2\ 2.x Directory that contains the HTML files generated by Sandcastle for help 2.x only.
Help\{Project Name}.hhp 1.x Html Help Workshop project
Help\{Project Name}.hhc 1.x Html Help Workshop table of contents
Help\{Project Name}.hhk 1.x Html Help Workshop index
Help\{Project Name}.HxC 2.x Collection definition
Help\{Project Name}.HxT 2.x Table of contents
Help\files.HxF 2.x Included file list
Help\index_a.HxK 2.x Associative index
Help\index_b.HxK 2.x Dynamic link index
Help\index_s.HxK 2.x Search window index
Help\index_k.HxK 2.x Keyword index
Help\index_n.HxK 2.x Named URL index
Help\index_f.HxK 2.x Context-sensitive index

Note: In the DocSite templates the compiled help files (.chm and .HxS) are copied to the Help\bin\ folder instead of the project's output directory, which is commonly bin\Debug\ or bin\Release.

Viewing the Output Files

After a DocProject or DocSite is built, all of the project items that you have selected to include will be visible in Solution Explorer. Hidden output can be viewed in the Solution Explorer by selecting the project and clicking the Show All Files tool button or by selecting Show All Files from the Project menu.

Viewing Sandcastle's Output

Sandcastle's HTML output is copied into the Html and Html2 folders, which you may have already included as project items. More output is located in a directory named buildhelp, such as the reflection files that were generated by Sandcastle and the XML documentation files (code comments) of the source projects.

Help 1.x
To view the Help 1.x output in Visual Studio Standard edition or higher, click the Invoke Help 1.x Output tool bar button Invoke Help 1.x Output Tool Bar Button.

Alternatively, and for Express users, double-click the {Project Name}.chm file in Solution Explorer. If you haven't included the compiled help file as a project item then click the Show All Files button to see it in Solution Explorer and then double-click it.

Help 2.x
To view the Help 2.x output in Visual Studio Standard edition or higher, click the Invoke Help 2.x Output tool bar button Invoke Help 2.x Output Tool Bar Button.

Note that .HxS files are not associated with any program by default, so clicking this button will typically result in a prompt that reports this very issue. You can download a viewer, such as Namespace# or H2Viewer and associate it with the .HxS extension:
  1. Browse to the .HxS file in Windows Explorer and double-click it.
  2. When Windows asks you to locate a program for this file extension browse to a tool that can view the file, such as Namespace# or H2Viewer.
  3. Make sure to check, Always use the selected program to open this kind of file and click OK.
You can integrate the collection into Visual Studio using the Help Integration Wizard, which is also useful for distributing the compiled help file to other developers. For more information, see How to: Use the Help Integration Wizard to Add a Help Collection to Visual Studio

Note: The Help Integration Wizard (HIW) is sensitive to things like spaces in the names of certain files and settings, but it doesn't provide any warnings or diagnostic information when it's configured improperly. Instead, your collection will simply not show up in Document Explorer after it's installed. Therefore, it's imperative that you follow the instructions closely and only change other settings if you are fully aware of the potential consequences. And when in doubt, do not enter spaces or symbols that may cause the installer to not function properly.

Viewing DocSites

With DocSites you can also run the solution as you would a normal ASP.NET Web Application project to view the help in your DocSite web interface. Press Ctrl+F5 to build the project and have it start in a web browser or press F5 alone to build and attach the debugger.

For more information about DocSites, see DocSite Templates.
For more information about templates in general, see DocProject Templates.

Last edited Jun 10, 2008 at 5:10 PM by davedev, version 41


No comments yet.