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:
  • Visual Studio 2005 or 2008.
    • The latest DocProject release only provides a single installer but supports both versions of Visual Studio.
    • Service Pack 1 is also required for Visual Studio 2005.
    • Visual C# Express and Visual Basic Express may be used instead (see below for details).
    • English only; other languages may not be compatible.
  • The Sandcastle May 2008 Release is required to use the Sandcastle and Sandcastle/Deployment build engines. (These are the only engines provided 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:
  • Firefox 2.0.0.9
  • Opera 9.24
  • Windows Internet Explorer 7.0.6000.16575
  • Microsoft Internet Explorer 6.0.2900.2180; SP2
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
  • Open System Properties: Start > Control Panel > System or right-mouse click the My Computer icon and select Properties.
  • Go to the Advanced tab.
  • Click the Environment Variables button.
  • In the User variables list, highlight the DXROOT variable and click Delete.
  • Ensure that the DXROOT variable exists in the System variables list and that it specifies the root installation directory of the latest Sandcastle release (commonly, C:\Program Files\Sandcastle\).
  • Click OK three times to exit all of the dialogs.
Windows Vista Instructions
  • Open System Properties: Logo > Control Panel > System or right-mouse click the Computer icon and select Properties.
  • In the pane on the left click Advanced system settings
  • Go to the Advanced tab.
  • Click the Environment Variables button.
  • In the User variables list, highlight the DXROOT variable and click Delete.
  • Ensure that the DXROOT variable exists in the System variables list and that it specifies the root installation directory of the latest Sandcastle release (commonly, C:\Program Files\Sandcastle\).
  • Click OK three times to exit all of the dialogs.
  • Close the System window.

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:
  • Visual Studio 2005 and 2008 Standard or higher
  • Visual C# 2005 and 2008 Express
  • Visual Basic 2005 and 2008 Express
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:
  • The framework reflection data files must have a document model applied, but since DocProject will only generate these files once, the model for the Sandcastle presentation style that you've chosen for your project will be used and all subsequent projects, regardless of the presentation style, will use the original framework reflection files.
  • If the build fails before DocProject has completed generating the framework reflection data, then you must delete the %DXROOT%\Data\Reflection\ folder and start again. DocProject will not attempt to create the missing framework reflection data so if you do not delete the folder then DocProject will assume that the data is already present.
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:
  • Docsite Templates, Windows Security Issue
  • This issue affects the DocSite templates only, in any language.
  • Sandcastle/Deployment and FTP
  • When using the Sandcastle/Deployment build engine provider, if you specify an FTP url for the target location then the source directory structure must already exist on the target machine.
  • Improved Vista Support
  • DocProject has strict CAS requirements that require administrative privileges, which means that Visual Studio must be started with Run as Administrator on Vista when UAC is enabled.

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:
  • There are no known issues that are specific to this version of Visual Studio.

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:
  • identical installation as the full version, except that the Add-In is not installed in express editions.
  • support for both Visual Basic and Visual C# DocProject templates, depending upon the versions of Visual Studio that are installed.
    • Note: DocSite templates are not currently supported in Visual Web Developer Express.
  • the New Project Wizard, which starts when a new DocProject is created.
  • the MSBuild task that starts the help build process inside Visual Studio and outside, such as on the command-line or a build server.
  • a custom Build Process Component, without Visual Studio automation capabilities.
  • configurable project folders and items such as presentation and configuration files for Sandcastle (e.g., sandcastle.help1x.config).
The following features are currently unavailable to express editions but are available using the DocProject External UI:
  • the ability to cancel help builds.
  • partial and skipped builds.
  • tools options pages for managing build engines and active project settings.
  • content and topic management dialogs.
  • the Include Project Output Dialog that allows users to easily import project items after each build.

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?

Last edited Jul 3, 2008 at 3:18 PM by davedev, version 12

Comments

No comments yet.