DocProject 1.10.0 Release Candidate

Feb 9, 2008 at 1:11 PM
DocProject 1.10.0 Release Candidate is now available for download on CodePlex.

Lots of bug fixes and new features:

  • 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.