DocProject's Build Process

Introduction

Generating documentation with DocProject is easy. It can be done in Visual Studio by simply building a DocProject or DocSite in the same way that other projects are built (separate or as part of the solution), on the command-line using MSBuild, on a build server (e.g., Team Build), or by the DocProject External UI.

For more information, see How To Build Compiled Help With DocProject.

Process and Extensibility
DocProject provides a pluggable architecture that is configured using a standard .NET configuration file and .NET 2.0 Providers.

A registered provider creates a build engine that builds help for DocProjects and DocSites. The project's build engine defines a set of steps to be executed by the underlying engine and can perform various tasks outside of the pre-defined build steps as well, such as preparing the project to be built by creating or cleaning the target directory structure, importing files, or even deploying output once it's built.

For help creating a custom build engine, see Creating a Build Engine Provider.

MSBuild

DocProjects and DocSites are built by the Add-In when they are built inside of Visual Studio; however, MSBuild is used to start the process. This means that the projects can be built externally by MSBuild, on the command-line or by a build server. Visual Studio does not have to be running and the Add-In does not have to be loaded; however, the assembly in which the add-in is defined also defines the MSBuild tasks that are used by the DocProject and DocSite templates so it must be present on the system that is building the projects.

DocProject installs the DaveSexton.DocProject.dll assembly into your system's global assembly cache (GAC) when you use the DocProject installer. The other MSBuild task dependency is the DaveSexton.DocProject.targets file, which is installed in DocProject's bin folder; commonly, C:\Program Files\Dave Sexton\DocProject\bin. The DocProject installer creates an environment variable named, DocProjectPath that references DocProject's installation directory. It's used by the DocProject and DocSite templates to locate the .targets file.

When you build a DocProject or DocSite the assembly output is built first by MSBuild, and if that succeeds documentation is then generated by the project's build engine.

Build Process Component

Before documentation is generated, DocProject will instantiate the registered build process component, if one exists.

A build process component allows developers to hook into the start and end of the build process, and the start and end of each individual build step, to execute custom code written in the DocProject's or DocSite's selected language. This allows developers to customize the build process by managing the collection of build steps and performing custom tasks during each build on a per-project basis.

The build process component must be built into the DocProject's or DocSite's assembly output and registered with the project itself. When regsitered, DocProject will attempt to instantiate the component in its own AppDomain. In order for DocProject to communicate with the component across an AppDomain boundary, a build process component proxy is created. The component can communicate back to the DocProject Add-In through a build process component marshaler. This is completely transparent to developers, however.

Build Process Component Pipeline
Figure 1: Build Process Component communication pipeline

Build Steps

The particular build engine used by your DocProject or DocSite creates a set of predefined steps that build the project's output.

You can open Visual Studio's Output window to view the progress while documentation is being built for your DocProject or DocSite. Each step may output its own progress information.

Note: If the output is not displayed then make sure that Tools > Options > Projects and Solutions > Build and Run > MSBuild project build output verbosity is set to Normal or higher.

For more information about build steps, see How To Build Compiled Help With DocProject.

Build Types

There are 3 types of builds that may occur for DocProjects and DocSites: Full, Partial and Skip.

Each build type is chosen by the Add-In based on the criteria discussed below. Having different build types provides more flexibility and control over DocProject and DocSite content.

The build type is also assignable programmatically, which may override the Add-In's default process for choosing an appropriate build type. This feature provides a means for custom build engines to modify the build type based on custom criteria. After each build the engine's build type is automatically reset to Default.

Note: Build types do not have any effect on whether Visual Studio will build the assembly output of a DocProject or DocSite. The build types are only used by the Add-In to determine how the compiled help output will be built, if at all.

Full Help Build

Each time a DocProject or DocSite performs a full build, all of the project's output is recreated from the assembly output of the project references, and also any external sources and conceptual topics in the project. Modifications to any of the build items that are produced by the build engine are lost.

Criteria must be met in order for a full build to be executed.

What actions can cause a full help build?
  • Using the Rebuild command in Visual Studio or the DocProject External UI.
  • Changing the registered type name of the build process component, removing the existing registration or adding a registration will always cause a full build the first time the project is built thereafter.
  • Deleting any of the partial build items in the project causes a full build. (For more information about partial build items read the next section about partial builds.)
  • When a build updates the assembly output of referenced projects, the referencing DocProject or DocSite will perform a full build.
  • When certain project options and settings are modified a full build may be required.
Precedence
A full build takes precedence over the other build types. If the criteria for a full build has been met then a full build will be executed.

Partial Help Build

This feature allows build engines to optimize the build process by reusing the output from a previous build.

The Sandcastle build engine, for instance, skips all of the steps up to the final steps when a partial build is executed. Only the final steps are executed, which creates the compiled help files for help 1.x and 2.x using their respective compilers and the source items from the last full build. The actual steps that are executed depends on whether the template is configured to build help 1.x, help 2.x, both or neither of them.

Partial builds also provide a way for developers to modify the Html Help Workshop files (Help 1.x) and the MS Help 2 files (Help 2.x) and have the DocProject or DocSite only rebuild the compiled help, forgoing the full Sandcastle build process. For more information, see Creating Custom Topics.

Note: Changes to partial build items (more on these below) are not persisted. The next full build will replace these items.

What actions can cause a partial help build?
  • Modifying, but not deleting, any of the partial build items will cause a partial build.
Precedence
A partial build may only occur if the criteria for a full build hasn't been met.

Partial Build Items
Partial build items are indicated by the engine that provides them.

For instance, the Sandcastle build engine uses the Sandcastle tools to generate Html Help Workshop files that may be included as project items. These items are special to the Sandcastle build process and are marked with partial-build priority. (See Sandcastle Build Items below for more information).

Skip Help Build

A skipped build means that the compiled help is not built for the DocProject or DocSite.

This feature allows developers to work on a DocProject or DocSite's assembly output without having the help built each time the project is built. Modifying source code files and then building the project will not cause help to be built if the project's output is already up-to-date with respect to the sources and build items.

What actions can cause a help build to be skipped?
  • When no changes are detected for the engine's build items, assembly output of project references, external sources, conceptual topics and certain project options, the help build is skipped.

General Build Items

The following items are not specific to any build engine.

Item NameMissing Build ActionUpdated Build ActionIs build output?
App_Data\DocSiteContents.xmlFullNoneYes
App_Data\DocSiteIndex.xmlFullNoneYes


The DocSiteContents.xml and DocSiteIndex.xml files only apply to the DocSite templates and their build actions may be overriden by build engine providers.

Sandcastle Build Items

In the case of the Sandcastle build engine, all of the Help 1.x and Help 2.x files must be present for a partial build to occur, depending upon which help versions a project is configured to build. Modifying any of those files may cause a partial build to be executed, but deleting any of them will always cause a full build to be executed.

The following table illustrates the build types chosen by the Sandcastle build engine depending upon the state or existence of several special project items. The build types listed relate to building the compiled help output only, not the assembly output.

Help VersionItem NameMissing Build ActionUpdated Build ActionIs build output?
1.xHelp\Presentation\Style\Configuration\sandcastle.help1x.configErrorFullNo
1.xHelp\Presentation\Style\Configuration\conceptual.help1x.configErrorFullNo
2.xHelp\Presentation\Style\Configuration\sandcastle.help2x.configErrorFullNo
2.xHelp\Presentation\Style\Configuration\conceptual.help2x.configErrorFullNo
N/AHelp\Presentation\Style\Configuration\MRefBuilder.configErrorFullNo
1.xHelp\Settings\Projects\help1x.configErrorPartialNo
2.xHelp\Settings\Projects\help2x.xsltErrorPartialNo
N/AHelp\Topics\ErrorFullNo
N/AHelp\Settings\conceptual_art.xmlErrorFullNo
N/AHelp\Settings\conceptual_snippets.xmlErrorFullNo
N/AHelp\Settings\bibliography.xmlErrorFullNo
N/AHelp\Settings\tokens.xmlNoneFullNo
N/AHelp\Settings\metadata.xmlNoneFullNo
N/AHelp\Settings\links.xmlNoneFullNo
N/AHelp\Settings\conceptual_project.xmlNoneFullNo
N/AHelp\Settings\conceptual_version.xmlNoneFullNo
N/AHelp\Topics\Html\**\*.htmNonePartialNo
N/AHelp\Settings\topics.xmlNoneFullNo
N/AHelp\Comments\project.xmlNoneFullNo
N/AHelp\Settings\dynamicFilters.xmlNoneFullNo
N/AHelp\Settings\versions.xmlNoneFullNo
1.x{Project output directory}\{Project Name}.chmFullNoneYes
2.x{Project output directory}\{Project Name}.HxSFullNoneYes
1.xHelp\Html\FullNoneYes
2.xHelp\Html2\FullNoneYes
1.xHelp\{Project Name}.hhpFullPartialYes
1.xHelp\{Project Name}.hhcFullPartialYes
1.xHelp\{Project Name}.hhkFullPartialYes
2.xHelp\{Project Name}.HxCPartialPartialYes
2.xHelp\{Project Name}.HxTFullPartialYes
2.xHelp\files.HxFPartialPartialOnly when missing
2.xHelp\index_a.HxKPartialPartialOnly when missing
2.xHelp\index_b.HxKPartialPartialOnly when missing
2.xHelp\index_f.HxKPartialPartialOnly when missing
2.xHelp\index_k.HxKPartialPartialOnly when missing
2.xHelp\index_n.HxKPartialPartialOnly when missing
2.xHelp\index_s.HxKPartialPartialOnly when missing
N/AApp_Data\DocSiteContents.xmlPartial (overridden)NoneYes
N/AApp_Data\DocSiteIndex.xmlPartial (overridden)NoneYes


The {project output directory} is commonly bin\Debug or bin\Release, depending upon the selected Configuration. However, in the DocSite templates the compiled help (.chm and .HxS) is always copied to Help\bin\ instead.

The Html and Html2 items only refer to folders, not each individual file contained by them.

The rules of precedence for each build type affects whether a partial build will be executed. For example, this means that even if you update the project's .hhk file, a partial build will not be executed if the .hhp file is missing.

Modifying Help 1.x and Help 2.x files
The Sandcastle build engine will delete the existing output before each full build since its purpose is to generate these files. For this reason you should always make a backup of the Help 1.x and Help 2.x files if you change them and merge your changes manually into the output of the next full build.

Note: Configuration options are provided for the help project files (.hhp and .HxC) so that the build output does not have to be modified. See How To Configure DocProject for more information.

Last edited Jun 9, 2008 at 7:17 PM by davedev, version 25

Comments

No comments yet.