How To Configure DocProject
Introduction
DocProject may be configured via the
Tools >
Options >
DocProject >
Engines page or on a per-project basis via the
Tools >
Options >
DocProject >
Active Projects page. In Visual Studio Standard and higher you can right-mouse click the project node in Solution Explorer and select
DocProject Properties to open a tool window that is similar to the
Active Projects page.
When a new
DocProject or
DocSite is first created, the
New Project Wizard provides an easy way to choose required and optional settings. For more information, see
Configuring Projects with the New Project Wizard.
Each
DocProject can have settings that are distinct from other
DocProjects, even within the same solution. Project options are persisted in the project file itself (e.g., .csproj, .vbproj). Engine options (technically, build engine provider options) are stored in the current user's isolated storage area.
Plug-ins can extend DocProject's
Engines and
Active Projects pages to include custom options for a custom build engine and individual
DocProjects and
DocSites.
DocProject External UI
The Express editions of Visual Studio do not allow add-ins, which means that the configuration dialogs and build options that are provided by the DocProject Add-In are not supported.
Although, the
DocProject External UI (
DocProject.exe) program provides the same tools that are available in Visual Studio Standard and higher via the
Active Projects tools options page. The external user interface also provides support for choosing the current
Configuration and
Platform, and for building the project and its project references using
MSBuild.
DocProject Tools Options Pages
DocProject provides two separate pages for configuration options:
Engines and
Active Projects. A third page,
Alerts, exists in source code but is not included by the installer since its functionality is incomplete.
Engines Page
The
Engines page provides configuration settings for each build engine that is registered with DocProject. Currently, the only build engine supplied by the installer is for
Sandcastle. The
Sandcastle/Deployment plug-in that is installed with DocProject actually just extends the Sandcastle build engine by adding a new build step and providing deployment configuration options, but defers all of the base functionality to the Sandcastle build engine.
For more information on the Sandcastle/Deployment build engine, see
Sandcastle Deployment Plugin.
Grid SettingsThe grid allows you to customize settings for the currently selected item in the drop-down list.
The following table lists the settings for the build engines that are installed with DocProject. The
Inheritable column is used to indicate those settings that you may override on individual
DocProjects and
DocSites via the
Active Projects page. In other words, some settings on the
Engines tab provide the default values for
DocProjects and
DocSites that have not overridden them. The
Default Value column indicates the default value for each setting. For settings where
Inheritable is
Yes, the
Default Value column indicates the value that all
DocProjects and
DocSites will use unless explicitly overridden.
Sandcastle Options Category | Property | Description | Inheritable | Default Value |
Configuration | Html Help Workshop | Full path and file name of the Html Help Workshop program, hhc.exe | No | %ProgramFiles%\Html Help Workshop\hhc.exe (expanded) |
Configuration | Sandcastle | Full path to the directory where Sandcastle is installed. | No | %DXROOT% (expanded) |
Sandcastle/Deployment Options Category | Property | Description | Inheritable | Default Value |
Deployment Proxy | Use Proxy | Indicates whether deployment will use the proxy information. | Yes | False |
Deployment Proxy | Server | Specifies the location of the proxy that will be used for deployment. | Yes | Not Set |
Deployment Proxy Authentication | Use default credentials | Indicates whether the default credentials should be used for the deployment proxy. Set this property to False to specify custom credentials. | Yes | True |
Deployment Proxy Authentication | User name | Specifies the proxy user name that should be used for deployment. This property is only used when the Use default credentials property is False. | Yes | Not Set |
Deployment Proxy Authentication | Password | Specifies the proxy password that should be used for deployment. This property is only used when the Use default credentials property is False. | Yes | Not Set |
Active Projects Page
The
Active Projects page provides a list of all of the
DocProjects and
DocSites in the active solution. The grid allows you to customize settings for the currently selected
DocProject or
DocSite in the drop-down list.
Note: The grid is the same regardless of whether you open it in
Tools >
Options or by right-mouse clicking a project node in Solution Explorer and selecting
DocProject Properties.
The configurable properties, independent of the selected build engine, are as follows:
Category | Property | Description | Default Value |
Build | DocProject version | Read-only settings that indicates the version of DocProject that was used to create the DocProject or DocSite. | N/A |
Build | Build engine | Read-only setting that indicates the build engine used by the DocProject or DocSite. The engine is chosen via the New Project Wizard when the project was first created and cannot be changed. | N/A |
Build | Documentation scope | Specifies the scope for documentation to be included in the build output. This setting can be used to configure the inclusion of internal members or to restrict the documentation to public members only. | PublicOnly |
Build | External sources | List of external files or folders that will be included in the generated help. | 0 (zero) |
Extensibility | Process component type name | Specifies a type that derives from BuildProcessComponent to receive notifications of various build events. Enter a full type name, assembly-qualified type name or a full type name with an absolute or relative assembly path, separated by a vertical bar; e.g., MyNamespace.MyType | ..\anotherproj\bin\Debug\anotherproj.dll. | Auto-generated |
Include Project Output Dialog | Apply to all default | Specifies whether Apply to all will be checked when the user is prompted to include certain, predetermined files and folders in the project after the build has completed. | False |
Include Project Output Dialog | Include project output default | When Don't ask me this again is True, specifies whether certain, predetermined files and folders will be included in the project after the build has completed. | False |
Include Project Output Dialog | Don't ask me this again | Specifies whether the user will be prompted to include certain, predetermined files and folders in the project after the build has completed. | False |
Sandcastle OptionsThe Sandcastle build engine adorns
DocProjects and
DocSites with more settings, some of which have default values that are inherited from a corresponding setting on the
Engines page. These settings appear in the grid along with the other, default project settings:
Category | Property | Description | Default Value |
Build | Version management | Specify multiple versions for each project reference and external source. Version information will be included in the auto-generated reference documentation. | N/A |
Build | Missing dependencies | List of dependencies (assemblies) that cannot be detected automatically by DocProject. | 0 (zero) |
Build | Use friendly HTML file names | Enable this setting to have Sandcastle create file names based on the name of each topic's API instead of the much shorter GUID form. | False |
Build | Help 1.x | Project options for the HTML Help Workshop. Also indicates whether the DocProject or DocSite will produce a .chm file. | N/A |
Build | Help 2.x | Project options for the MS Help 2 collection. Also indicates whether the DocProject or DocSite will produce an .HxS file. | N/A |
Build | Build assembler options | Various options that affect the behavior and performance of Sandcastle's Build Assembler utility (normally the longest running step in the help build process) and whether diagnostic information is captured. | Trace Errors, Cancelable |
Configuration | Documentation set name | Specifies the base file name for build output and the project name as it should appear in the help topics. | Name of the project |
Configuration | MRefBuilder configuration file name | Specifies the name of the configuration file to be used by the MRefBuilder program and the Topic Management dialog. The file must be located in a Configuration folder in the Presentation Path (e.g., Presentation\Style\Configuration\). | MRefBuilder.config |
Configuration | Help Version 1.x reference configuration file name | Specifies the name of the configuration file to be used by the Build Assembler when building Help 1.x reference documentation. The file must be located in a Configuration folder in the Presentation Path (e.g., Presentation\Style\Configuration\). | sandcastle.help1x.config |
Configuration | Help Version 2.x reference configuration file name | Specifies the name of the configuration file to be used by the Build Assembler when building Help 2.x reference documentation. The file must be located in a Configuration folder in the Presentation Path (e.g., Presentation\Style\Configuration\). | sandcastle.help2x.config |
Configuration | Help Version 1.x conceptual configuration file name | Specifies the name of the configuration file to be used by the Build Assembler when building Help 1.x conceptual documentation. The file must be located in a Configuration folder in the Presentation Path (e.g., Presentation\Style\Configuration\). | conceptual.help1x.config |
Configuration | Help Version 2.x conceptual configuration file name | Specifies the name of the configuration file to be used by the Build Assembler when building Help 2.x conceptual documentation. The file must be located in a Configuration folder in the Presentation Path (e.g., Presentation\Style\Configuration\). | conceptual.help2x.config |
Configuration | Show entire build component stack | Indicates whether the build component stack options (below) will display all build components when expanded or just those that have an associated editor. | False |
Configuration | Help 1.x reference build component stack | Sandcastle build components in the Help 1.x reference configuration file. | N/A |
Configuration | Help 2.x reference build component stack | Sandcastle build components in the Help 2.x reference configuration file. | N/A |
Configuration | Help 1.x conceptual build component stack | Sandcastle build components in the Help 1.x conceptual configuration file. | N/A |
Configuration | Help 2.x conceptual build component stack | Sandcastle build components in the Help 2.x conceptual configuration file. | N/A |
Content | Generate root API topic | Specifies whether to generate a root topic for reference documentation, which will contain all of the namespace topics in the table of contents (TOC). | False |
Content | Merge xml documentation | Indicates how XML documentation generated by the Topic Editor will be merged with XML documentation comments from source code. Documentation is automatically merged per element; e.g., summary, remarks and example. | Overwrite |
Content | Topic Management | Provides tools for managing the table of contents (TOC), filtering, conceptual documentation, and reference XML documentation for the project, namespaces and API elements. For more information, see How To Use the Topic Management Dialog. | empty |
Content | Topic Designer | Provides the ability to design content that is shared among all topics, such as a header and footer. | empty |
Presentation | Presentation Style | Read-Only setting that indicates the Sandcastle presentation type chosen when the DocProject or DocSite was created by the New Project Wizard. | N/A |
Presentation | Presentation Path | Path to the DocProject or DocSite's Sandcastle presentation directory. The value can either be relative to the project's root directory, which is the default, relative to the Sandcastle installation directory or an absolute path. | Presentation\Style\ |
For more information about the
Build Component Stack options, see
How To Use Third-Party Build Components in DocProject.
Sandcastle/Deployment Options Category | Property | Description | Default Value |
Deployment | Enabled | Indicates whether the build output will be deployed to the Target Location after a successful help build. | False |
Deployment | Content | Indicates the source content that will be deployed to the Target Location. | Chm, Hxs |
Deployment | Target Location | Specifies the path to where the build output will be deployed. Local file, UNC, HTTP, HTTPS and FTP paths are supported, as well as any other Uri schemes that are registered at runtime with the WebRequest.RegisterPrefix method. | Not Set |
Deployment Authentication | Use default credentials | Indicates whether the default credentials should be used for deployment. Set this property to False to specify custom credentials. | True |
Deployment Authentication | User name | Specifies the user name that should be used for deployment. This property is only used when the Use default credentials property is False. Credentials are only used when Target Location is an HTTP, HTTPS or FTP address; otherwise, this property is ignored. | Not Set |
Deployment Authentication | Password | Specifies the password that should be used for deployment. This property is only used when the Use default credentials property is False. Credentials are only used when Target Location is an HTTP, HTTPS or FTP address; otherwise, this property is ignored. | Not Set |
Deployment Proxy | Use Proxy | Indicates whether deployment will use the proxy information. | Inherited |
Deployment Proxy | Server | Specifies the location of the proxy that will be used for deployment. | Inherited |
Deployment Proxy Authentication | Use default credentials | Indicates whether the default credentials should be used for the deployment proxy. Set this property to False to specify custom credentials. | Inherited |
Deployment Proxy Authentication | User name | Specifies the proxy user name that should be used for deployment. This property is only used when the Use default credentials property is False. | Inherited |
Deployment Proxy Authentication | Password | Specifies the proxy password that should be used for deployment. This property is only used when the Use default credentials property is False. | Inherited |
For more information about the Sandcastle/Deployment engine see,
Sandcastle Deployment Plugin.
Alerts Page
The
Alerts page is a work-in-progress that will allow a user to configure a single email address and SMTP server information for notification of the success or failure of
DocProject and
DocSite builds. This page is not currently visible in the tools options dialog but it is present in the source code.