This project is read-only.

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 Settings
The 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 Options
The 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.

Last edited Jun 11, 2008 at 5:50 AM by davedev, version 31

Comments

No comments yet.