DocProject for Sandcastle

What is DocProject?

DocProject integrates the Sandcastle compiled help builder into the Visual Studio 2005 IDE. A new project template is provided that builds a compiled help file (.chm) for all of its project references. This facilitates the administration and development of project documentation by allowing developers to use a single solution for their projects and related code documentation. Optionally, the compiled help output can be included into the documentation project for further development. The DocProject installer only installs support for building compiled help from a specialized VS 2005 project template. No other features, add-ins or tools are installed. DocProject completely automates the process by examining the project for references to other projects and building the documentation from their assembly output. The user does not have to perform any manual steps for the build to work. Dependency information is taken from the project’s references automatically. The documentation is built by simply building the project.

In order to use DocProject you must have installed the following components:

• .NET Framework 2.0
• Visual Studio 2005 (Express Edition is not supported)
• Html Help Workshop 1.4 SDK [1]
• Sandcastle December 2006 CTP [2]
• DocProject for Sandcastle (Installer) [3]

You can download DocProject for Sandcastle here or in the references section at the end of this blog entry [3].

Known Issues

• Although the installer allows the installation path to be changed, doing so breaks the Add-In, which requires the installed path to be: C:\Program Files\Dave Sexton\DocProject for Sandcastle.
• Uninstallation does not remove the C# Project Documentation template or the Add-In
.
• Only one comment file can be used per solution since Sandcastle expects a file named comments.xml by default. This means that if multiple projects with comments.xml files are referenced only one comments.xml will be used, indeterminately, when the help is compiled.

License

This software is licensed under the CC-GNU GPL.

Copyright © Dave Sexton 2006-2007

Installation and Source Code

A Windows Installer package (.msi) has been created to install both the Add-In and "C# Project Documentation" template along with the complete source code and C# project file (.csproj) [3]. The installer uses a Community Components installer file (.vsi) to install the Add-In and Template. Currently, the uninstallation of the Windows Installer package does not remove the Add-In or DocProject template; however, they can be removed easily by opening the configured Add-In and Template directories and deleting the DocProject files manually.

To compile the source code, locate the .csproj file in the C:\Program Files\Dave Sexton\DocProject for Sandcastle\Source folder. The existing build event (on successful build) requires another component for zipping the output in preparation for installation. The component is called DSZip and can be downloaded with the complete source code at [4]. I'll blog about this simple console application in the future if there are enough requests for that.

DocProject Components

Templates

Currently, the only DocProject template is the "C# Project Documentation" template, based on a C# class library. In the future there may be support for a web project (ASP.NET documentation website). Also, there may be support for the execution of custom code from within the project itself.

Add-In

The build process for projects created from the DocProject template are controlled by an Add-In named, "DocProject for Sandcastle". Without the Add-In projects created from the DocProject template are just plain C# class libraries.

Usage Instructions

The following steps can be taken to use DocProject after it has been successfully installed:

1. Create or open an existing solution.
2. Add a project that you want DocProject to generate documentation for its assembly output.
3. Add a new project to the solution and select the C# Project Documentation template.
   1. Select Visual C#.
   2. In the right pane look under My Templates.
4. Name the new project anything that you'd like and create it.
5. Add project references using the dialog that appears or cancel the operation and add the references as you normally would by using the Solution Explorer.
6. Build the solution or project to see DocProject in action.
7. Optionally, but recommended, open up the solution configuration and remove your documentation project from the build process.

Note that the build output (compiled help (.chm) and supporting files) are replaced each time a DocProject is built.

Configuration

DocProject installs a custom tools options page named, DocProject. It appears under Dave Sexton's Tools in the Options dialog accessible via the Tools menu. The dialog configures settings on a per-project basis.

Code Plex

I've submitted a request to Code Plex for the addition of this project. I'll create a new blog entry when I hear back from them :)

--
References

[1] HTML Help 1.4 SDK
Microsoft HTML Help Downloads
http://msdn.microsoft.com/library/default.asp?url=/library/en-us/htmlhelp/html/hwMicrosoftHTMLHelpDownloads.asp

[2] Sandcastle - December 2006 Community Technology Preview (CTP)
http://www.microsoft.com/downloads/details.aspx?FamilyID=E82EA71D-DA89-42EE-A715-696E3A4873B2&displaylang=en

[3] DocProject for Sandcastle Installer
http://www.codeplex.com/DocProject/Release/ProjectReleases.aspx

[4] DSZip Installer
http://www.codeplex.com/DocProject/Release/ProjectReleases.aspx

As always, I'd love to hear from anyone that has something to say about this post.  Drop me a comment.