About DocProject

C# DocProject VB.NET DocProject C# DocSite VB.NET DocSite

Part I: General Information Part II: Details and screenshots Part III: How to proceed

Overview

DocProject is an open source help authoring tool (HAT) that consists of Visual Studio Project Templates ("documentation" projects), a Visual Studio Add-In and a public API, providing an extensible platform for authoring, managing and building compiled help in various formats.

The latest version of Microsoft Sandcastle is used to build HTML help topics in various presentation styles, such as one that looks like the documentation for Visual Studio and the Microsoft .NET Framework. Conceptual documentation is authored using Microsoft Assistance Markup Language (MAML) and reference documentation is generated automatically for managed assemblies.

DocProject also automates HTML Help compilers to produce Help 1.x (.chm) and Help 2.x (.HxS) output in a single build. A compiled help file may contain auto-generated reference documentation, conceptual documentation and custom HTML topics.

Using DocProject, help authors and developers can build documentation easily, both inside and outside of Visual Studio 2005, 2008, Visual C# Express, Visual Basic.NET Express, on the command-line using MSBuild, on a build server such as Team Build, or in the DocProject External UI program.

Background
This project was started in December of 2006 by Dave Sexton. He continues to be the sole coordinator and developer on the project.

DocProject was built from the ground up in C# and will continue to be written in C#, exclusively. The entire Visual Studio Solution, including projects for the installer and supporting controls, are distributed with DocProject's installer.

The lastest version of DocProject targets the Microsoft .NET Framework 2.0 and is built in C# 3.0 using a Visual Studio 2008 solution and projects.

Features

See the Home page for a comprehensive list of features.

Visual Studio Integration

Building project documentation is quick and easy with Visual Studio project templates that compile help for project references and an Add-In that provides additional features.
See also Visual Studio Integration below and DocProject Components.

Input/Output

Build Process and Extensibility

DocProject's build process is highly automated and extensible:
See also Build Process, Creating a Build Engine Provider and How to Use Third-Party Build Components In DocProject.

Help Authoring

DocProject provides features that make it easy to create shared content for Sandcastle, external XML documentation, the table of contents (TOC) and various ways to manage the topics that will be included.

Visual Studio Integration

DocProject integrates seamlessly into Visual Studio and provides many features that will help you to configure your projects and write documentation.

The following screenshot shows the first 3 steps of the New Project Wizard:

First three steps of the New Project Wizard
Figure 1: First three steps of the New Project Wizard

The following screenshot shows DocProject's Topic Explorer, Topic Filters and DocProject Properties tool windows being used to configure a DocSite in Visual Studio 2005:

Topic Explorer, Topic Filters and DocProject Properties tool windows
Figure 2: Topic Explorer, Topic Filters and DocProject Properties tool windows

For Help Authors

As an author you can use DocProject to write conceptual documentation and produce various output types, such as raw HTML help topics, Help 1.x (.chm), Help 2.x (.HxS) or even an ASP.NET Web Application, called a DocSite, for publishing documentation to the web or a company intranet.

The following screenshot shows an example of a DocSite in Internet Explorer 7. The example project uses the BasicBlue theme that comes with DocProject. An auto-generated reference topic built with Sandcastle's Visual Studio 2005 presentation style has been selected in the table of contents (TOC) on the left:

See also DocSite Example Images
DocSite using Sandcastle's Visual Studio 2005 presentation style - Shown in Internet Explorer 7
Figure 3: DocSite using Sandcastle's Visual Studio 2005 presentation style - Shown in Internet Explorer 7.

Sandcastle can automatically generate reference documentation for projects within the same solution, external assemblies and even entire directories. XML documentation comments from your source code are included. You can also use DocProject's Topic Editor to create external comments that will be merged with your code comments during builds.

The following screenshot shows an external documentation comments summary being edited for an auto-generated reference topic in DocProject's Topic Editor:

See also Topic Management Dialog Images
Topic Editor - Editing an external _summary_ for an auto-generated reference topic
Figure 4: Topic Editor - Editing an external summary for an auto-generated reference topic.

For Developers

As a developer you have full control over the entire build process. You can create custom project templates and plug-ins, called Build Engine Providers, which integrate seamlessly into Visual Studio and the external GUI to build help in proprietary formats.

DocProject comes with a plug-in for Sandcastle that you can choose when creating new DocProjects and DocSites. You can even create custom build engine providers that inherit from the Sandcastle provider to add additional features. For example, DocProject has another provider called Sandcastle/Deployment, which extends the base Sandcastle build engine by adding automatic deployment capabilities. It can be used to deploy compiled help and DocSite content to the local computer, the company intranet or an FTP server.

There's also an extensibility feature that works on a per-project basis. It's called a Build Process Component, and each of the built-in project templates provides a basic implementation for you out-of-the-box. A build process component can be edited using the language chosen for the project; e.g., C# or VB.NET. It allows a developer to modify the build process from within the project itself. You can perform external tasks, trace output and even add dynamic build steps in the code editor. Build the project to see your changes take effect immediately.

The following screenshot shows the build process component for a C# DocProject. This example uses the BuildStarting method to insert a dynamic build step into the build process:

Build Process Component in C#
Figure 5: Build Process Component in C#

Application Programming Interface (API)

DocProject's public API provides utilities that you can use while taking advantage of its extensibility features in several different places, such as with custom build engine providers, build process components, Sandcastle build components and dynamic topic filters.

Use the API to help simplify or automate common tasks for users. For example, you can inject custom steps into the New Project Wizard, manage source projects, persist and retrieve project options, engine configuration and various build settings, work with XML documentation and reflection files, create custom menus and tool windows in Visual Studio, and custom toolbars in both VS and the external GUI, run builds, trace output, log runtime exceptions, and more.

Getting Started

To start using DocProject download the latest release. Make sure to read the information on the releases page and in the Latest Release Notes before installing DocProject.

Note: The current release supports both Visual Studio 2005 and Visual Studio 2008 with a single installer.

Browse the Wikimap for preliminary documentation and tutorials. Subscribe to Dave Sexton's blog for supplementary information and previews of upcoming releases.

To provide feedback please use the Discussions area and the Issue Tracker here on CodePlex, or contact Dave Sexton through his blog.

Next Steps

After successfully installing DocProject and its dependencies:
  1. Start Visual Studio and load up an existing solution with projects that you want to document.
  2. Choose a DocProject template and create a new project. See How To Create a DocProject for a new solution or Creating a DocSite (Quick Start) for help.
  3. Configure the new project with the New Project Wizard and make sure to select at least one of the compiled help formats; e.g., Help 1.x (.chm) or Help 2.x (.HxS).
  4. If you have selected project references in the last wizard step then you can build the project now to produce auto-generated reference documentation; although, you may want to continue reading and configure more project options first.
  5. To configure project options in Visual Studio Standard or higher, open the DocProject Properties window by right-mouse clicking your project in Solution Explorer and then click DocProject Properties. Alternatively, and for Express users, run the DocProject External UI program (Start > All Programs > DocProject > DocProject External UI) and then open the project that you just created.
    1. Add external sources using the External sources option.
    2. Manage version information using the Version management option if you have multiple versions of the same assemblies. Version information for each API will appear in auto-generated reference documentation.
    3. If you chose the Sandcastle/Deployment build engine in the first step of the New Project Wizard, configure deployment settings and set the Deployment enabled option to true.
    4. Browse the other options to configure the project and to familiarize yourself with them.
  6. Manage the table of contents in the Topic Explorer tool window by clicking the Topic Explorer button on the Sandcastle tool bar Sandcastle Tool Bar - Topic Explorer.
  7. Add new topics and author conceptual documentation in Microsoft Assistance Markup Language (MAML) and it will be combined automatically with reference documentation in a single build, using the same presentation style.
  8. You can also extend the build process to include raw HTML topics in the compiled help. See Creating Custom Topics for more information.
  9. In Topic Explorer, click the filter button to manage topic filters or double-click a topic to open the Topic Editor (for conceptual topics, Visual Studio's XML editor will be opened).
  10. If your project is based on a standard DocProject Template then build now to produce documentation. Compiled help can be found in the project's bin directory for the current solution configuration.
  11. If your project is based on a DocSite Template, set it as the startup project and press Ctrl+F5 to build the project and automatically launch the website when it's completed.
    1. Click the Admin link and log in using the credentials that you specified in the New Project Wizard.
    2. Configure DocSite settings using the administration page.
    3. When you are done configuring settings, publish the DocSite to a web server or your local IIS by right-mouse clicking the project in Solution Explorer and clicking Publish....
  12. Send feedback to Dave Sexton :)