Configuring Projects with the New Project Wizard

The New Project Wizard makes it easy to configure new DocProjects and DocSites in Visual Studio. The wizard is available in all supported versions of Visual Studio according to the Latest Release Notes, including Express editions.

The wizard will start automatically when you create a new DocProject or DocSite. For help creating new projects, see Creating a DocProject for a new solution or Creating a DocSite (Quick Start).

This article examines the default steps of the New Project Wizard and also the custom steps that are included by the Sandcastle build engine provider.

Step 1: Choose a Build Engine

Choose a Build Engine

This step asks you to choose the build engine for your project. There can be only one engine used by a project and once the type is chosen it cannot be changed.

DocProject is a foundation on which help authoring tools can plug-in to Visual Studio. The .NET 2.0 Provider model is used to register Build Engine Providers, which provide Build Engines that can build help for project references and external sources. The foundation also provides a public API and various utilities for things like creating new tool windows and tool bars.

A Sandcastle build engine is built-in to DocProject so that it appears in the drop down list of this step automatically. Another plug-in, Sandcastle/Deployment extends the Sandcastle plug-in by providing deployment capabilities.

You can also create your own custom Build Engine Providers and inherit from the Sandcastle build engine to add new features or modify the default behavior. For more information, see Creating a Build Engine Provider.

Note: The next steps are determined by the build engine provider that you choose. Therefore, you must decide whether you're going to require deployment capabilities before moving on to the next step. If you change your mind during a later step and go back to this step, all of your changes to subsequent steps will be lost by selecting a different build engine provider.

Step 2: Choose a Sandcastle Presentation

Choose a Sandcastle Presentation

All of the Sandcastle presentation styles that are registered with DocProject are available in the drop down list. You must choose one style only and your choice cannot be modified once the wizard has completed.

You can create custom presentation styles and then register them with DocProject to have them shown in this wizard step. To register your styles you must edit the DaveSexton.DocProject.dll.config file, commonly found in C:\Program Files\Dave Sexton\DocProject\bin. Review the current style registrations as examples.

This step, as with all of the steps up until Step 7, are included by the Sandcastle build engine provider. Step 7 and Step 8, however, are included by DocProject regardless of the selected build engine provider.

Note: The Sandcastle/Deployment provider inherits from the Sandcastle provider, so it includes these steps too.

Step 3: Import Topics and Settings

Import Topics and Settings

This step allows you to specify the full path and name of a DocProject or DocSite project file from which to import conceptual topics, project options and other settings.

After you complete the wizard it will begin to configure your new project. If you have specified a project file in this step then DocProject will try to import files and settings and only fall-back to the Sandcastle installation if version conflicts or other errors are detected. When it's complete a dialog will be shown with any warning messages that were generated during the operation, unless there aren't any messages.

If you do not specify a project file then this step will be skipped. All required files will be imported from the Sandcastle installation and all project options and settings will have their default values.

Step 4: Choose Compiled Help

Choose Compiled Help

This step offers options for compiling help. Compiled help can also be configured later via the DocProject Properties window after the wizard has completed.

Help 2.x requires a Visual Studio SDK to be installed. If it's not detected then a hyperlink will appear so that you can download and install it. Once installed, you can press the Back button once and then press the Next button to return to this step with the Help 2.x option available.

Note: Visual Studio SDKs require Visual Studio Standard edition or higher to be installed. Express editions do not qualify.

Step 5: Locate the HTML Help Workshop

Locate the HTML Help Workshop

This step is only shown if Help 1.x output was enabled in the previous step but DocProject cannot locate the HTML Help Workshop compiler.

If you are presented with this step and you do not have the HTML Help Workshop installed, then go Back and either disable Help 1.x output or install the HTML Help Workshop before continuing.

If you do have the HTML Help Workshop installed then simply browse to the hhc.exe program and continue with the wizard by clicking Next.

The location of the HTML Help Workshop program can also be configured in the Tools > Options > DocProject > Engines page, with the Sandcastle build engine provider selected in the drop-down list.

Step 6: Create Shared Content

Create Shared Content

Shared content documents are XML files that are unique to each presentation style and contain localizable content that is included in topics when they are created by Sandcastle. You can use this step to change the markup that goes into the header and footer of all topics, for example.

Shared content may be edited at a later time via the Topic Designer.

Step 7: Create DocSite Credentials

Create DocSite Credentials

If you've chosen a DocSite Template then you will be presented with this wizard step. You may keep the default user name or specify your own, but you must enter a password and also verify it before moving on to the next step of the wizard.

The credentials that you enter are used to access the DocSite administration page. They are saved to the project's web.config file and the password is hashed using the algorithm specified in the project template, which is SHA1 in the templates that DocProject provides.

You can change the credentials at a later time by editing the web.config file.

Step 8: Choose Sources

Choose Sources

This is the final step of the wizard and it's shown regardless of the selected build engine provider.

All projects in the current solution that are supported as sources of documentation via project references are listed. You can choose any number of sources from the list, or none at all.

To add external sources use the External sources dialog, which supports assemblies, reflection files, folders and paths with wildcard characters as sources.

An external source is the only option for documenting Web Site projects (as opposed to Web Application projects) since they do not produce an assembly when built. For more information, see How to Build Help For a Web Site Project.

Project references can be added at a later time in the normal way that project references are added in Visual Studio.

External sources can be added at a later time via the External sources project option in the DocProject Properties window.

Last edited Jun 14, 2008 at 8:18 AM by davedev, version 8


No comments yet.