DocProject for Sandcastle

DocProject

Requirements | Features | Terminology | Plans | Development | Team | Help | Feedback

<Wikimap>

DocProject drives the Sandcastle help generation tools using the power of Visual Studio 2005/2008 and MSBuild. Choose from various project templates that build compiled help version 1.x or 2.x for all project references. DocProject facilitates the administration and development of project documentation with Sandcastle, allowing you to use the integrated tools of Visual Studio to customize Sandcastle's output.

For screenshots, an overview and how to get started, see About DocProject.

For news about DocProject, among other programming-related topics, see Dave Sexton's blog at http://davesexton.com/blog.

For more information about Sandcastle, see Sandcastle Help.

Requirements

Please read the Latest Release Notes for important information and additional requirements before downloading and installing DocProject.

To have all of DocProject's features available, Visual Studio 2005/2008 Standard or higher is recommended but there is also support for Visual C# 2005/2008 Express and Visual Basic 2005/2008 Express editions as well.

Features

Create external XML documentation for all API topics in source and design mode	Filter topics using checkboxes in a tree view, by regular expression, or by API type and accessibility	Graphical user interface for configuring and building projects outside of Visual Studio
Enlarge | Info	Enlarge | Info	Enlarge | Info
Figure 1: Topic Management Dialog - XML Comments	Figure 2: Topic Management Dialog - Topic Filter	Figure 3: DocProject External UI

Edit shared content items in source and design mode	Easily build an AJAX-enabled ASP.NET documentation website	Automatically deploy build output to the local network or an FTP server
Enlarge	Enlarge | Info	Info
Figure 4: Topic Designer	Figure 5: DocSite ASP.NET Web Application Example	Figure 6: Sandcastle/Deployment Plug-in

Automation
DocProject completely automates the process of building project documentation by examining your DocProjects and DocSites for references to other projects, building the documentation from their assembly output. You do not have to perform any manual steps for the build to work. Dependency information is taken from the project’s references automatically, so the documentation is built by simply building the project.

See also DocProject Templates, DocSite Templates, Build Process and DocProject External UI.

Integration
Having a Visual Studio project that builds compiled help for its project references makes building project documentation very flexible and easy. You have all of Visual Studio's IDE tools available to you, allowing you to customize the help with XML, HTML, icon and image editors. And with the DocSite templates, you can customize the default ASP.NET Web Application to fit your organization's particular needs.

See also DocProject Components.

Extensibility
DocProject is extensible, with plug-in support for custom build engines and an easy-to-use build process hook that is automatically set up for you when you create a new DocProject or DocSite. Modify the build process to your liking by handling build events in your favorite language: Visual C#, Visual J# or Visual Basic.

See also Build Process, Creating a Build Engine Provider and Sandcastle Deployment Plugin.

New Features in 1.10.1

• ResolveExternalLinksComponent Beta 2 does not require a separate download for DocProject users. The component is automatically added to the Help 1.x and Help 2.x reference stacks in new DocProjects and DocSites.
• Various important bug fixes.

New Features in 1.10.0

• Much better performance in Visual Studio and the DocProject External UI while executing Sandcastle's Build Assembler (the longest running step in the process). Also worth noting is that DocProject now cleans up memory used by the Build Assembler as soon as it completes (memory usage is usually quite high during this build step).
• First-class support for building conceptual content using Sandcastle:
• Topics must be authored using Microsoft Assistance Markup Language (MAML). (For now, you can find more information about MAML and some links in this discussion.)
• New DocProjects and DocSites automatically include XML schema files that apply to MAML so that you can edit the XML-based conceptual topics with full IntelliSense in Visual Studio. (Note that although you should get IntelliSense as soon as you open a topic, I've found that it doesn't actually work unless you first open Help\Schemas\developer.xsd in the schema designer.)
• 19 conceptual topic templates are provided by DocProject. The template named, Conceptual is a general-purpose template that can be used to add additional content, whatever its nature may be, with the look and feel of auto-generated reference documentation and the ability to easily take advantage of presentation features like collapsible sections.
• When adding a new conceptual topic, DocProject will ask you which conceptual template you would like to use, while providing a preview of the MAML template's content.
• You can easily import existing MAML topics into your projects by clicking a tool bar button and browsing to the topics.
• Conceptual and auto-generated reference topics can link to each other. Note that reference topics must use HTML anchors while conceptual topics must use MAML (see the example at the bottom of each template). Drag & drop conceptual topic nodes from Topic Explorer into the Topic Editor to have links created automatically in reference topics.
• Three new tool windows for Visual Studio Standard edition and higher (the functionality that they provide is also provided by the Topic Management dialog for Express users):
• Topic Explorer: Appears similar to Solution Explorer but is used to manage the Table of Contents (TOC), conceptual documentation, Sandcastle API filters, and provides shortcuts to the other tool windows.
• Topic Editor: Provides an XML documentation editor for authoring content that will appear in auto-generated reference topics. Authored content is automatically merged at build-time with the XML documentation for each source.
• Topic Filters: Provides the ability to filter topics in the Topic Explorer by regular expression, categories such as API type and accessibility, and custom filters. It can also be used to manage dynamic filters that are executed during help builds.
• New filtering capabilities:
• Automatic dependency filtering for dynamic filters during builds; e.g., if a dynamic filter excludes a reference topic for a class, then DocProject will also remove the dependent topics such as, All Members, Methods, Properties, and the individual topics for each constructor, method, property, etc.
• Custom dynamic filters now have first-class support. They may provide an editor (user control) that DocProject can show in a modal dialog or on its own tab in the Topic Filters tool window. They can be configured to execute during help builds and can even be applied to the topics in Topic Explorer without requiring a build (excluded topics are unchecked so that Sandcastle's API filter will be used).
• A new Inheritance filter automatically filters all inheritance information for documented members and/or undocumented members, and supports a customizable list of API name prefixes used to include/exclude information about matching inherited members. The filter is not visible by default, but may be added to the Saved Filters list in the Topic Filters tool window. (It also serves as a working example of a custom dynamic filter.)
• Specify directories as sources for documentation, versions and missing dependencies.
• Sandcastle tool bar buttons for quickly launching a project's Help 1.x output (.chm) and Help 2.x output (.HxS). (Note that .HxS files aren't normally associated with a program that can view them, so the button normally just presents a message box stating that the file cannot be opened for this reason.)
• New MSBuild targets: BeforeRebuildHelp, AfterRebuildHelp, RebuildHelpDependsOn and RebuildBase.
• New project options for the Sandcastle and Sandcastle/Deployment build engines:
• Build assembler options: Allows you to tweak performance by enabling or disabling the ability to cancel Build Assembler while it's executing, and whether it should output information, errors and warnings.
• Documentation set name: The name of the project as it will appear in a CHM's title bar. It also serves as the base name for generated files (invalid characters are converted to underscores). The default value is the project's name.
• Generate root API topic: Specifies whether Sandcastle will generate a root topic (Namespaces) for reference documentation. (Note that Build Assembler in the Sandcastle January 2008 release throws an exception when this option is enabled, so it's disabled by default. However, Eric Woodruff has created Sandcastle Presentation File Patches that should allow you to enable this option.)
• New build component editors for a few of Sandcastle's built-in components:
• ForEachComponent: Build component stack editor dialog and recursive, expandable property.
• IfThenComponent: Build component stack editor dialog for two recursive, expandable properties (Then, Else).
• SharedContentComponent: Editor dialog and property expansion for the shared content files, with editable paths.
• TransformComponent: Editor dialog and property expansion for the XSL transformation files, with further expansion to editable arguments (both in-line value and a drop-down for inner XML).
• ResolveConceptualLinksComponent: Editor dialog and property expansion for the link targets, with editable link types.
• SyntaxComponent: Editor dialog and read-only property expansion for the configured syntax generators.

New Features in 1.9.0

• Compatibility with the Sandcastle October 2007 CTP.
• Preliminary support for conceptual content using Sandcastle's conceptual configuration file. (The conceptual build process has been integrated although it hasn't been tested and DocProject does not automatically generate a conceptual TOC yet.)
• Sandcastle's build component stacks are now available as properties in the DocProject Properties window and the DocProject External UI, with support for hosting custom build component editors that can either show a modal dialog, a drop down editor or sub properties.
• Framework and project reference link types are configurable as sub properties of the build component stacks and can be set by simply choosing one of the following values from a drop-down list: MSDN, Index, Local or None.
• DocSite Templates include four new buttons under the Contents tab: Save, Bookmark, Email and Print. The latter two are supported in IE6, IE7, Firefox and Opera, but the former two are only visible in IE. Note that Save does not currently download supporting files such as JavaScript or style sheets though.
• DocSite performance generating the full-text search index has been greatly improved.
• Version Management Dialog: Create documentation that includes version information by referencing external assemblies and reflection files, and then simply enter custom version names (DocProject uses Sandcastle's VersionBuilder program in the background.)
• ChmBuilder is used exclusively to build the supporting Help 1.x files (WARNING: The .HHC file format has been changed. Beware if you were modifying it to include custom topics.)
• Both the Topic Designer and API Topic Management dialog now remember their last saved position, size, and the positions of splitters.
• Edit all content item documents using the Topic Designer instead of just the shared_content.xml file. All of the available documents are listed in the Create Shared Content step of the New Project Wizard as well.
• Several new API Topic Management</