DocProject

C# DocProject VB.NET DocProject C# DocSite VB.NET DocSite

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
Topic Designer Topic Management Dialog External UI
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
Topic Designer DocSite ASP.NET Web Application Example Sandcaste/Deployment Plug-in
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.11.0
  • Compatibility with the Sandcastle May 2008 Release.
  • Full support for both Visual Studio 2005 and Visual Studio 2008 using a single installer.
  • Conceptual topics created in Topic Exporer are now saved with friendly file names and an .aml extension. A dependent companion file (.cmp) for storing metadata is created as well.
  • The topic import feature has been improved and now supports the inclusion of raw HTML topics in Topic Exporer. Legacy MAML topics (those with an .xml extension) are automatically imported into the new format and, if possible, a friendly name is chosen automatically.
  • An optional Import Topics and Settings wizard step has been added to the New Project Wizard. It allows for a single DocProject or DocSite file to be specified from which topics and settings will be imported into the new project automatically.
  • Wildcard characters, including directory recursion (**\ - but only on the most nested directory) is now supported in various dialogs, including External sources.
  • The External sources dialog is now available in the last step of the New Project Wizard.
  • Automatic checkout of source-controlled project items occurs whenever a project option or dialog must write to a file in the project.
  • ResolveExternalLinksComponent now works for conceptual builds and is automatically added to the conceptual configuration files when new DocProjects and DocSites are created. (The standalone release will also be updated.)
  • Open in Visual Studio toolbar button added to the DocProject External UI.
  • New Topic Explorer context menu commands: Copy as reference link, Copy as conceptual link and Copy as topic identifier.
  • New Topic Properties window that provides a user interface (UI) for editing conceptual topic metadata, such as Help 2.x DocSet attributes, index keywords and the topic's display title. This window is reachable by right-mouse clicking a conceptual topic in Topic Explorer and selecting Properties in the context menu.
  • New Help\Settings files are automatically included when DocProjects and DocSites are created:
    • conceptual_snippets.xml: Specifies code snippets written in multiple programming languages that may be included in conceptual topics.
    • tokens.xml: Specifies shared content items for both conceptual topics and XML documentation comments; items are referenced using <token>name</token> elements.
    • links.xml: Specifies external hyperlinks that can be used in both conceptual topics and XML documentation comments. (See ResolveExternalLinksComponent for more information.)
    • metadata.xml: Specifies global Help 2.x metadata that is inserted into all conceptual topics and auto-generated reference topics. Metadata can include attributes such as DocSet, Product, TargetOS and custom values.
    • bibliography.xml: Specifies global reference information for topic bibliographies. Conceptual topics and XML documentation comments that have citations as <cite>name</cite> elements will have bibliographies generated automatically.
  • New management dialogs for Help 1.x and Help 2.x configuration. (Settings are persisted to certain files in Help\Settings\Projects\, Help\Topics\Html\MSHelp2\ and the root Help\ folder.)
    • Configurable Help 1.x project options such as the list of source files, Binary TOC, Default Window and Display progress during builds.
    • Configurable Help 2.x project options.
      • Named URL values such as DefaultPage and HomePage, which may be chosen from a list of topics, and AboutPageInfo, EmptyIndexTerm and NavFailPage, which can be created with DocProject's HTML editor.
      • The Help > About image that appears in Document Explorer. (An HTML page that references the image is automatically generated for the AboutPageIcon named URL.)
      • Global metadata attributes, which are stored in Help\Settings\metadata.xml (more information above).
  • Improved MAML topic templates.
  • The behavior for detecting out-of-date sources and files has changed to allow for more control over change tacking.
    • Modifying individual conceptual topics may change the type of the next build. Changes are detected for MAML topics in Help\Topics\ and raw HTML topics in Help\Topics\Html\.
    • Starting Visual Studio and loading a DocProject or a DocSite does not force a full build anymore unless the output is actually outdated.
    • Another effect is that deleting the .chm or .HxS files no longer causes a partial build; instead, it always causes a full build. To force a partial build you must modify a partial build item.
  • Generate root API topic is now enabled by default in new DocProjects and DocSites.
  • Added inheritdoc tag to the DocProject configuration file so that it appears in the Topic Editor sections list when writing external XML documentation.
  • Numerous bug fixes.
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 dialog features:
    • Improved performance when applying filters.
    • Topic tree nodes now use icons that reflect access type, as do the tooltips.
    • Filter topics by API accessibility or in combination with API types; e.g., protected fields, private interfaces, public or protected methods and delegates, etc.
    • Save filters and load them later or have them applied automatically during builds (dynamic filters).
    • Author external XML documentation in the appearance of the selected presentation style, with special styles for XML documentation tags such as see, c, code, paramref, etc.
    • New XmlTreeView project and control, which supports binding to an IXPathNavigable data source and allows drag/drop internally and externally (although internal drag/drop support is not currently enabled. This feature is planned for conceptual content in a subsequent release).
    • Drag and drop API elements from the tree into the XML documentation editor to generate see links automatically (works in both source and design mode).
    • The appropriate XML documentation sections for each specific API type (.e.g, summary, remarks, return, value, etc.) are listed automatically in the XML documentation editor, including individual param and typeparam tags for methods and delegates.
    • Add additional documentation sections that support multiple instances (e.g., exception, permission) by selecting them from a drop-down list. The list only shows those sections that are appropriate for the selected topic.
    • Quickly create custom XML documentation sections in the editor by entering a name and pressing enter, or register them as built-in sections in DocProject's configuration file. See this blog post for information on how to use custom tags in Sandcastle's XSL transformations.
    • The XML documentation editor automatically cleans up empty sections from the external documentation when it's saved.
  • Build Process Components can now take advantage of more of DocProject's API and now have the ability to inject dynamic build steps, pass delegates to DocProject's API and register event handlers.
  • Documentation now includes a root Namespaces topic to which the XML documentation's project summary is applied.
  • Bug fixes and refactored code.
New Features in 1.8.0
  • Compatibility with the Sandcastle September 2007 CTP.
  • DocProject Properties context menu item for DocProjects and DocSites (on the project node in Solution Explorer) quickly opens a property page in Visual Studio Standard and higher.
  • DocSite Templates now support MSIE 6.0 (as well as IE 7.0, Firefox and Opera) and are themed, localizable, configurable and componentized.
  • DocSite Templates have a full-text search that supports complex query operations and uses an in-memory search index provider (based on .NET 2.0 Providers) that can be configured on the server, even after deployment.
  • DocSite Templates have a full-text index browse page that makes finding topics very easy.
  • The selected project Configuration and Platform work in MSBuild, Team Build and the DocProject External UI, which now displays drop-down lists for changing these values before building (like in Visual Studio).
  • The DaveSexton.DocProject.targets file has been refactored to make it more flexible.
  • Build output and Sandcastle project items are now located in a root folder named, Help.
  • After a build, compiled help is automatically copied to the project's output directory (for example, Debug\bin); however, for the DocSite templates the target is Help\bin. The DocSite TOC and index files are now generated in the App_Data folder.
  • DocProject External UI now supports the Include Project Output Dialog, which is automatically displayed after a build unless it's disabled by the user.
  • DocProject External UI provides a tools options page for configuring build engine providers just like the Engines tools options page that's available in Visual Studio Standard and higher.
  • Start Menu shortcuts to the DocProject External UI and various resources, including the Source folder in DocProject's installation directory, are now installed.
  • User configuration data is now stored in the system's isolated storage so that one user's changes do not overwrite another's; e.g., the default build engine provider and Sandcastle presentation style.
New Features in 1.7.0
  • The new DocProject 2008 Beta provides support for Visual Studio 2008 Beta 2 Standard and higher, Visual C# 2008 Express Beta and Visual Basic 2008 Express Beta.
  • DocProject External UI (DocProject.exe) allows users to configure and build DocProjects and DocSites outside of the Visual Studio IDE (intended specifically for VS Express users).
  • API Topic Management dialog contains an XML documentation editor that allows users to create external xml comments for all API members, namespaces and the project itself.
  • API Topic Designer displays a list of editable content items such as the topics' shared header and footer.
  • Sandcastle/Deployment Plug-In provides options to deploy various content files and DocSite files as well as the compiled help and build output.
  • The Missing Dependencies dialog allows you to add dependencies that DocProject cannot resolve automatically
  • Support for Team Build (requires community testing)
New Features in 1.6.2
  • Support for the Sandcastle June 2007 CTP Refresh.
  • External sources (assemblies and corresponding xml documentation) may be used along with project references.
  • Web Site Projects are now supported. See How To Build Help For a Web Site Project.
New Features in 1.6.1
  • Support for the Sandcastle June 2007 CTP
New Features in 1.6.0
  • Preliminary support for Visual C# 2005 Express and Visual Basic 2005 Express.
  • Support for Managed Visual C++ projects.
  • DocProjects and DocSites use an MSBuild task, enabling them to be built in Visual Studio, on the command-line or by a build server without any required modifications to the project files.
  • Sandcastle presentations are registered in DocProject's configuration file and custom presentations can be registered with DocProject as well.
  • The API Topic Designer allows users to edit shared API content (currently, the header and footer only) using an HTML editor.
  • The API Topic Management dialog enables users to edit project and namespace summaries in both text and HTML.
  • The API Topic Management dialog provides some new search options such as, "Find/Apply next match only" and "Show matching topics".
  • Users have the option to use friendly names or GUID names for the html files generated by Sandcastle. (Guid names are the default.)
  • A Sandcastle toolbar is installed in Visual Studio Standard edition or higher, with commands that open the API Topic Management Dialog and API Topic Designer for the currently selected project in Solution Explorer.
  • The width of the DocSite sidebar is now persisted in a cookie and preserved across post-backs and new sessions.
New Features in 1.5.0
  • API Topic Management dialog is a GUI to include or exclude particular API topics such as namespaces, types and almost any member, with regular expression and categorical filtering.
  • A copy of Sandcastle's MRefBuilder.config is imported into new DocProjects and DocSites. It can be edited manually or by using the API Topic Management dialog.
  • Build warnings and errors are added to Visual Studio's Error List, which is automatically shown to the user when a help-build fails with one or more errors.
  • The DocSite sidebar is now resizeable with the mouse and works with the latest Windows Internet Explorer, FireFox and Opera web browsers.
  • DocProject now works with projects nested in Solution folders.
  • The DocProject installer can be used to install for Everyone or Just me.
  • The project templates now appear in a DocProject category under Visual C# and Visual Basic in the New Project dialog . The templates remain available at the root nodes as well, but only for Just me installations.
  • The Visual Studio Content Installer is no longer used for installation, although the .VSI package is still built by the DocProject solution and included in the root installation directory.
  • The DocProject installer now works on systems where an Orcas CTP has been installed previously, although DocProject will only be installed in Visual Studio 2005.
  • After installing Sandcastle you no longer have to update comments.xml to comments*.xml in the configuration files. It is now done automatically, on a per-project basis, when you create a new DocProject or DocSite. (For more information see How To Install and Configure Sandcastle.)
New Features in 1.4.0
  • DocProject's Sandcastle build engine now uses the Sandcastle March CTP transformations.
  • DocProjects and DocSites can now build Html Help 1.x, Help 2.x, neither or both via a single build.
  • The New Project wizard has been extended for the Sandcastle build engine, allowing you to choose the type of help that your project will build (see previous feature).
  • DocSites use AJAX to improve client-side performance.
  • DocSite's index can be filtered, client-side.
  • The tools options page, "Dave Sexton's Tools", has been renamed to "DocProject" and was split into separate sub categories.
  • A status notification and progress bar now appear during help builds.
  • Improved error handling, including logging to the Application event log.
  • Several bug fixes.
New Features in 1.3.0
  • The New Project wizard has been extended to help you customize your new DocProjects and DocSites. Choose a build engine, customize the project's content and select the project references for which your project will build help.
  • For new projects that use the Sandcastle build engine, choose the base presentation directory (e.g., Prototype, vs2005) to be copied into the project. The sandcastle.config file is copied as well and then updated to point to the project's local XSL transformations and content files that are used by Sandcastle.
  • DocSite templates are now fully-functioning ASP.NET Web Applications that display the compiled help with an interactive TOC and index, breadcrumbs, an automatic header and footer, and a link to download the compiled help file (.chm).
  • Extended the build process to support Full, Partial and Skip build types.
  • The new Sandcastle/Deployment plug-in is provided as an example of the extensibility of DocProject and for use with your own DocProjects and DocSites. For more information on this plug-in see Sandcastle Deployment Plugin.
  • Added support for Visual Studio's Clean and Rebuild commands.
  • The installation directory can now be changed when installing DocProject.
  • Uninstalling DocProject from Add/Remove Programs now completely removes all of the installed Visual Studio content (the add-in and templates) and the assemblies installed in the GAC. Note: The manual steps required to uninstall 1.2.1 and earlier versions still apply when installing the 1.3.0 release. For more information, see How To Uninstall DocProject.
Previous Updates
  • New: Release Candidate 1.2.0 provides a few new templates, including support for Visual Basic.NET and an ASP.NET DocSite. Some of the code base has been refactored again and more work items have been addressed.
  • New: Release Candidate 1.1.0 provides support for easy, out-of-the-box extensibility for projects based on a DocProject template. Also, DocProject provides plug-in support for build engines other than just Sandcastle, however, the Sandcastle engine is currently the only engine included (Sandcastle utilities require a separate download).

Terminology

DocProject usually refers to the collective purpose of DocProject's Visual Studio Project Templates and Visual Studio Add-In. In certain contexts, however, DocProject may refer solely to the Add-In, which is technically the actual "software" and the guts of DocProject.

DocProjects are Visual Studio projects based on a DocProject Template.
DocSites are Visual Studio projects based on a DocSite Template.

Plans

DocProject is an ongoing effort, which requires collaboration, feedback and support from the community. Please use the Forums and Issue Tracker to provide us with your questions and valuable comments so that we can develop DocProject into an asset for Visual Studio users.

In the future we hope to:
  • include better support for globalization
  • build documentation for the DocProject Add-In library itself
  • perform continued development with team members from the .NET community to extend the functionality of DocProject

Development

DocProject has been and will continue to be developed using the C# language, exclusively.

Team

If you're interested in joining the DocProject team then please contact Dave Sexton. Don't forget to specify your desired role and to include some information about your competencies for that role. You may want to also briefly include your motivation for becoming a DocProject team member.

Help

In the How To... wiki there is guidance for performing common tasks associated with DocProject and Sandcastle, such as installation, configuration, usage and tutorials.

Here are some links to get you started:

Installation, Configuration and Uninstallation Using DocProject Tutorials

Feedback

Use the Discussions tab to submit questions and comments pertaining to DocProject. Please use the Issue Tracker tab to submit bug information and feature requests.

If you have questions related to the licensing of DocProject, or any concerns that you wish to keep private, please contact Dave Sexton.

Last edited Jul 19, 2008 at 6:01 AM by davedev, version 171