Part I: General Information
Part II: Details and screenshots
Part III: How to proceed
DocProject is an open source help authoring tool (HAT) that consists of Visual Studio
("documentation" projects), a Visual Studio
and a public API, providing an extensible platform for authoring, managing and building compiled help in various formats.
The latest version of Microsoft
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
, 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
This project was started in December of 2006 by
. 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
, 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.
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
- 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
- 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,
- 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
- 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.
Creating a Build Engine Provider
How to Use Third-Party Build Components In DocProject
DocProject provides features that make it easy to create shared content for Sandcastle,
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
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
The following screenshot shows DocProject's Topic Explorer
, Topic Filters
tool windows being used to configure a DocSite
in Visual Studio 2005:
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
, 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
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:
DocSite Example Images
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
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 Management Dialog Images
Topic Editor - Editing an external summary
for an auto-generated reference topic.
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
. 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
, which extends the base Sandcastle build engine by adding automatic deployment capabilities. It can be used to deploy compiled help and
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
method to insert a dynamic build step into the build process:
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
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.
To start using DocProject download the
. Make sure to read the information on the releases page and in the
Latest Release Notes
before installing DocProject.
The current release supports both Visual Studio 2005
and Visual Studio 2008
with a single installer.
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.
After successfully installing DocProject and its dependencies:
- Start Visual Studio and load up an existing solution with projects that you want to document.
- 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.
- 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).
- 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.
- 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.
- Add external sources using the External sources option.
- 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.
- 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
- Browse the other options to configure the project and to familiarize yourself with them.
- Manage the table of contents in the Topic Explorer tool window by clicking the
Topic Explorer button on the Sandcastle tool bar .
- 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.
- You can also extend the build process to include raw HTML topics in the compiled help. See
Creating Custom Topics for more information.
- 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).
- 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.
- 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.
- Click the Admin link and log in using the credentials that you specified in the
New Project Wizard.
- Configure DocSite settings using the administration page.
- 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
- Send feedback to Dave Sexton :)