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.
  • DocProject Templates are used to create new projects that encapsulate all of the settings and data that is required to generate an entire documentation set.
  • The New Project Wizard guides you to setting up your project with steps that let you choose, for example, a Sandcastle presentation style, compiled help output and project references.
  • Edit Sandcastle configuration files and XSL transformations using Visual Studio's built-in XML editor to easily customize a presentation style without affecting other projects.
  • Configure projects in Visual Studio with various tool windows: Topic Explorer, Topic Filters, Topic Editor and DocProject Properties.
  • Alternatively, configure projects outside of Visual Studio using the DocProject External UI (which is the only option for Express users).
See also Visual Studio Integration below and DocProject Components.

Input/Output

  • Auto-generated reference documentation for library, executable and Web Application projects in Visual C#, Visual J#, Visual Basic and Managed Visual C++ can be built using project references from within a single Visual Studio solution.
  • Web Site projects and assemblies built outside of Visual Studio, in any language, can be added as external sources (see How To Build Help For a Web Site Project).
  • DocProject can also build documentation for unmanaged APIs that have a reflection file generated by another tool; for example, AjaxDoc generates reflection data and XML documentation for Atlas JavaScript libraries.
  • Conceptual documentation written in Microsoft Assistance Markup Language (MAML) is built with the same look and feel as auto-generated reference documentation and combined in a single build to produce mixed documentation sets.
  • HTML topics are always produced when using Sandcastle.
  • DocProjects can be configured to produce compiled Help 1.x, Help 2.x, or both via a single build.
  • DocSites are DocProjects that also build an AJAX-enabled ASP.NET Web Application for easily creating and publishing online documentation for the web or a company intranet.

Build Process and Extensibility

DocProject's build process is highly automated and extensible:
  • To generate documentation simply build the project.
  • DocProject examines your DocProjects and DocSites for references to other projects, building the documentation from their assembly output.
  • DocProject discovers dependencies automatically by examining sources using reflection, and it will even trace dependencies to the GAC.
  • Automatically deploy build output and various project items to an HTTP, FTP, UNC or local target using the Sandcastle/Deployment Plug-In.
  • Create plug-ins for custom build engines that can be completely proprietary or inherit from the Sandcastle build engine, with full access to DocProject's public API.
  • Take control over the build process on a per-project basis by handling build events in your favorite language (e.g., C#, VB.NET) using a Build Process Component, which is automatically set up for you when you create a new DocProject or DocSite.
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.
  • Version information for your projects can be included in documentation using the Version Management dialog.
  • A WYSIWYG XML designer is provided for editing or creating shared content that appears in all topics, such as a header and footer.
  • The designer can also be used to create external XML documentation, such as a summary, remarks and an example, for all API topics in both source and design modes.
  • While you author external XML documentation in the designer it has the appearance of the chosen Sandcastle presentation style.
  • Easily insert images, standard HTML tags and XML documentation tags like <c> and <see> in shared content and external XML documentation.
  • Images that are included in the XML documentation designer are imported into the project and the path to the image is rebased automatically in the XML.
  • Drag API topics from a tree view into your external XML documentation and a <see> link is created automatically.
  • Drag & drop conceptual topics in the same tree view to quickly organize the table of contents (TOC).
  • Individual API topics can be excluded by unchecking them or by applying regular expression and categorical filters (see How To Use the Topic Management Dialog).
  • Save filters to be used again later. Check the Build checkbox and they become dynamic filters that are applied automatically during each help build.
  • You can even create a custom dynamic filter with an editor control that DocProject will display in a tab page or a modal dialog.

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 :)

Last edited Jun 9, 2008 at 5:40 AM by davedev, version 13

Comments

No comments yet.