DocProject: Latest Release Notes

Introduction

This document contains important instructions and information relating to the installation of DocProject 1.11.0 Release Candidate. Please read this carefully before installing DocProject or any of its dependencies.

Important: Existing DocProjects and DocSites created by DocProject 1.10.1 and earlier are not compatible with this release. You must create a new project and use the Import Topics and Settings step in the New Project Wizard to perform the update automatically.

For a list of new features added to this release, see the New Features section on the home page.
For information about API and architectural changes, including notable breaking changes, refer to the changeset comments in the Source Code area of this website.

Additional Software

DocProject requires additional software to be downloaded and installed separately. Some of the software is optional depending upon the features that you will use.

Please read Required Software and Optional Software below to determine which software you must install before installing DocProject.

Required Software

The following software is required by DocProject:
Required Software for DocSites
In Visual Studio 2005 the following software is required to use the DocSite Templates (a flavor of DocProject Templates that build an ASP.NET documentation website):
Note: Visual Studio 2008 does not require a separate installation of AJAX Extensions because the .NET 3.5 Framework has the AJAX assemblies built-in.

Supported Browsers for DocSites
The DocSite templates build a website that has been tested for compatibility with the following web browsers only: Earlier versions of MSIE such as 5.5 have not been tested and might not be compatible.

Optional Software

Optional software is recommended, but not required for DocProject's standard feature set.

Presentation Patch
Download and apply the latest patch from Sandcastle Styles before using DocProject.

This patch provides bug fixes for common issues with Sandcastle's presentation styles and also adds additional features that are supported by DocProject.

Web Site Projects
Download the latest release of Documenting Web Projects to get new code providers that make it easy to extract assemblies and XML documentation files from Web Site projects.

Note: This download is not required for Web Application projects, which can be added to DocProjects and DocSites as project references instead of as external sources.

For more information about Web Site projects, see How To Build Help For a Web Site Project.

Compiled Help
DocProjects and DocSites can automate the process of building compiled help 1.x and 2.x if the following software is installed:

Help 1.x: HTML Help Workshop
Install the workshop compiler if you want DocProject to build a distributable help package (.chm file) that can be opened on any Windows system, stand-alone or included as part of the documented application for context-sensitive help.

Help 2.x: Visual Studio SDK (2005, 2008)
Install the SDK if you want DocProject to build a help collection (.HxS file) that can be merged with Visual Studio's help collections. This is useful for add-in, control and package developers that integrate their products into Visual Studio.

Important SDK Installation Notes
When you install a Visual Studio SDK you must manually delete the DXROOT user environment variable that the installer creates for an older CTP version of Sandcastle.

Windows 2003/XP Instructions Windows Vista Instructions

Installation

The DocProject installer provides Visual Studio templates, a Visual Studio Add-In and a Sandcastle plug-in for DocProject. After installing DocProject it will be ready to use in all supported versions of Visual Studio; however, Sandcastle and other tools must be installed separately.

To install DocProject:
  1. Download the latest release
  2. Close all running instances of Visual Studio.
  3. Double-click the installer to begin the installation.
    1. Vista users: right-mouse click and select Run as administrator instead.
  4. When presented with the option to choose the target versions of Visual Studio, only the versions that are detected on your system and supported by DocProject will be listed.
    1. Note: Express editions are not listed separately. For example, if you choose to install for Visual Ssudio 2005, that includes all supported versions of Visual Studio 2005 that you have installed on your system.
The DocProject installer can install DocProject for Everyone or Just me in the following versions of Visual Studio if they are detected on your system: Detailed instructions for installation, configuration and general usage can be found in the How To... wiki.

.NET Framework Reflection Data

The latest Sandcastle installer contains the .NET Framework reflection data files that are used to link to MSDN content.

Important Note for DocProject 1.8.0 RC Users
When DocProject 1.8.0 RC was released the Framework reflection data files had to be generated manually by end-users, so DocProject automated the process.

The reflection files that DocProject generated were saved under Sandcastle's installation folder, however, uninstalling both DocProject and Sandcastle does not remove them. You must manually delete the %DXROOT%\Data\Reflection\ folder and all of its subfolders before installing the latest release of Sandcastle; otherwise, if you've already installed the latest version of Sandcastle, then you must reinstall Sandcastle after manually deleting this directory.

%DXROOT% is commonly, C:\Program Files\Sandcastle.

Auto-generation
DocProject is configured to automatically generate these files the first time a DocProject or DocSite is built if they do not exist, however there are some things to be considered:
More information can be found in a thread on the MSDN forums: http://forums.microsoft.com/MSDN/ShowPost.aspx?PostID=2217724&SiteID=1.

Using Multiple Presentations Styles
If you plan on using different presentation styles then you may want to enable DocProject to build distinct reflection data files for each presentation. To enable this feature you must install DocProject and then:
  1. Open DocProject's configuration file, commonly found at C:\Program Files\Dave Sexton\DocProject\bin\DaveSexton.DocProject.dll.config.
    1. Note: Do not confuse it with the DocProject.exe.config file.
  2. For each registered presentation (each <add> element under the <presentations> element), set the fxReflectionDataDirectory attribute to the name of a subfolder that DocProject will create under %DXROOT%\Data\Reflection for the presentation's framework reflection data.
    1. Note: If you want to share the same framework reflection data between two presentations, such as Visual Studio 2005 and Sandcastle Hana, simply use the same subfolder. For example, fxReflectionDataDirectory="VS2005".
    2. Note: If the specified subfolder already exists then DocProject will not build the framework reflection data for that particular presentation style.
  3. Uncomment the three <add> elements at the end of the configuration file (after the "Update .NET framework reflection data path" comment).
  4. For each previously uncommented <add> element, set the replaceWith attribute to the value specified in the corresponding presentation's fxReflectionDataDirectory attribute, which you set previously.
    1. Note: Specify the full path in the replaceWith attribute; e.g., %DXROOT%\Data\Reflection\VS2005.
Generating Framework Reflection Data Manually
If you do not want DocProject to generate reflection data automatically for any presentation style, you must install DocProject and then:
  1. Open DocProject's configuration file. (See above for more information.)
  2. Set the generateFrameworkReflectionData attribute to False.

Known Issues

Some of the following issues cannot be resolved manually and others will be resolved in subsequent releases. Fixes will be noted as they become available.

All Versions of DocProject

The following issues apply to all versions of DocProject:

DocProject for Visual Studio 2005

The following issues only apply when DocProject is used in Visual Studio 2005:

ClickOnce Sources
Projects that build an executable that is deployed using ClickOnce cannot be referenced by other projects in Visual Studio, so they must be referenced as external sources instead. See the following article for more information:

DocProject for Visual Studio 2008

The following issues only apply when DocProject is used in Visual Studio 2008:

Support for Visual Studio Express editions

Support for Visual Studio Express editions is limited because they do not allow add-ins. However, the DocProject External UI (DocProject.exe) can be used to configure and build DocProjects and DocSites that are created in express editions.

DocProject supports the following features in express editions of Visual Studio: The following features are currently unavailable to express editions but are available using the DocProject External UI:

Source Code

The DocProject installer does not provide the source code anymore. To download the source code, visit the Source Code area of this website.

DocProject's Visual Studio 2008 solution and projects have been tested on multiple systems in an attempt to make them usable, out-of-the-box.

For help using DocProject's Visual Studio solution and projects, see How To Use The Source Code.

DSZip Utility

Download and install the DSZip utility if you plan on using the supplied Visual Studio solution to build the Visual Studio Content Installer file (.vsi) or the Windows Installer package (.msi) using the DaveSexton.DocProject.InstallActions project.

If you are not planning on using the solution file or projects to build the installers, or if you're not even planning on using the source code at all, then you do not need the DSZip utility.

Note: DSZip version 1.1.0 is provided on the release page. This is the same version that was provided in previously releases of DocProject, so if you've already installed it then there is no need to download it again.

For more information, see How To Use The Source Code, Projects.

Getting Started

After reading this article and successfully installing DocProject and its dependencies, see About DocProject, Getting Started if you are a new user.

Help

For information about how to properly request assistance and how to resolve issues on your own, see How to Diagnose and Resolve Issues.

Links to documentation can be found in the Wikimap.

Various help topics and tutorials can be found in the How To... wiki.

Feedback

Thanks for your interest in DocProject. Any feedback you can provide will be appreciated.

What can I do to improve DocProject for you or your organization?