Sandcastle Help File Builder

News Feeds

Welcome to the Sandcastle Help File Builder

Sandcastle, created by Microsoft, is a tool used for creating MSDN-style documentation from .NET assemblies and their associated XML comments files. The current version is the May 2008 release. It is command line based and has no GUI front-end, project management features, or an automated build process like those that you can find in NDoc. The Sandcastle Help File Builder was created to fill in the gaps, provide the missing NDoc-like features that are used most often, and provide graphical and command line based tools to build a help file in an automated fashion.

Tip: See the Installation Instructions for information about the required set of additional tools that need to be installed, where to get them, and how to make sure everything is configured correctly.

Tip: If you are new to Sandcastle and the help file builder, see the topics in the Getting Started section to get familiar with it, set up your projects to produce XML comments, and create a help file project.

Benefits and Features

Using the help file builder provides the following advantages:

• The GUI interface provides an NDoc-like properties window so anyone familiar with NDoc should be quite comfortable using it. In addition, it provides a Visual Studio-like project explorer that lets you manage and edit the files associated with the project.
• The builder can produce an HTML Help 1.x (.CHM) file, an HTML Help 2.x (.HxS) file, and/or a website.
• The HTML Help 2.x output includes a valid set of collection files and an H2Reg.exe configuration file to simplify deployment and integration of the help file into existing collections such as those used by Visual Studio.
• The website output contains an HTML and an ASP.NET index page with tree view that can be used to navigate the table of content and a full-text index search feature.
• The settings are saved in a standard MSBuild-format project file and can be built from within the standalone GUI, from the command line using MSBuild, or in a post-build step to a Visual Studio project that runs MSBuild. Support for full Visual Studio integration is planned for a future release.
• A project file conversion option is provided to convert projects from other third-party tools such as NDoc, DocProject, SandcastleGUI, and the example GUI provided with Sandcastle to the help file builder's MSBuild project format.
• Visual Studio 2005/2008 solution and project files are supported directly as documentation sources. When the help project is built, the assembly, XML comments file, and reference information is imported from them and used automatically.
• In addition, both executable (.EXE) and library (.DLL) assemblies can be added individually as documentation sources along with any related XML comments files.
• Dependency references can also be specified individually. File, GAC, project, and COM references are supported (COM references are supported in the project file but currently cannot be added via the standalone GUI).
• The builder will automatically locate both Sandcastle and the HTML help compilers by looking at the common environment variables, in the system path, and in the Program Files special folder on all fixed hard drives. Properties are also supplied for you to specify the paths in the off-chance that it cannot locate them automatically.
• The build process provides full logging and error handling. All output from the build is stored in a log file in the output folder. The log is in XML format and can be ran through an XSL transformation to make it more readable, to highlight warnings and errors, etc.
• The intermediate files used to create the help file are placed in a working folder beneath an output folder of your choosing. They can be automatically removed after a successful build or kept around for further modifications.
• Most of the NDoc features have been built into the Sandcastle help file builder including:
• Definition of project summary and namespace summary comments that will appear in the help file. You can also easily indicate which namespaces to include or exclude from the help file. Support is also included for specifying namespace comments via a NamespaceDoc class within each namespace.
• The ability to turn off documentation of attributes and various other unwanted API elements.
• Automatic determination of the default topic for the help file.
• You have control over the help file name, title, header text, and footer information such as the e-mail address, copyright text, and copyright URL.
• Support for conceptual content is fully integrated. This allows you to define additional content that appears in the table of content such as usage notes, tutorials, etc. Conceptual content is created using Microsoft Assistance Markup Language (MAML).
• Standard HTML files can also be included and merged with the table of content. A site map file can be used to define the layout.
• Language selection and localization support is built in. Translations are provided for the help file builder resource files in several languages and information is provided on how to localize the Sandcastle content files.
• Steps have been taken to make the build process more open so that you have a chance to customize it without having to modify the code for the builder application itself. Custom build process plug-ins are supported that can be used to extend or alter the build process in various ways. Plug-ins supplied with the help file builder include:
• Additional Content Only - Build help files based on nothing but the conceptual and/or additional content items (no API content).
• Additional Reference Links - Add additional sources of reference links for third-party libraries or MSDN content that does not appear in your help file.
• AjaxDoc Builder - Build help files for Atlas script libraries in conjunction with AjaxDoc.
• Completion Notification - E-mail the build results to someone optionally attaching the log file (raw or transformed via XSL).
• DBCS Fix for CHM Builds - Fixes the HTML content and runs the Help 1 compiler in the proper locale to overcome its encoding issues.
• Hierarchical Table of Content - Used to rearrange the table of content such that namespaces are nested within their parent namespaces.
• Output Deployment - Copy the resulting help file to a file share, web server, FTP site, etc.
• Script# Reflection File Fixer - Fixes up the reflection information file so that Script# assemblies are documented correctly.
• Table of Content Exclusion - Used to exclude API members from the Table of Content (the members still appear in the help file).
• Version Builder - Generate version information for the current project and others related to the same product and merge that information into a single help file for all of them.
• The plug-in interface is public and is documented in this help file allowing you to create your own custom plug-ins.
• Support is included for the <inheritdoc /> tag which allows you to inherit documentation from base types/members. This is implemented via a standalone tool so it can also be used by other third-party tools and build scripts. This tool provides features beyond those found in the build component supplied with Sandcastle.

In addition to the help file builder, the following custom build components are supplied:

• A code block component that extends the <code> XML comment tag with file inclusion, syntax highlighting, line numbering, collapsible #region and #if/#else/#endif sections, and a copy to clipboard option. This is useable in both reference and conceptual content.
• A post-transform component that can be used to add a logo image to the header of each page, make some minor adjustments to the syntax section, and add basic version information to the help topics. This is useable in both reference and conceptual content.
• A "show missing" component that adds "missing" notes for missing summary, returns, param, value, and remarks documentation tags and that can also auto-document constructors.
• An IntelliSense component used to extract the XML comments into files that can be used for IntelliSense. Only the basic set of tags needed for IntelliSense are exported and only for documented API members. This can greatly reduce the size of the IntelliSense files and removes all private implementation details when only documenting the public API.
• A help attribute component that can be used to add extra MSHelp:Attr attributes to each generated API topic. This is useful for adding extra DocSet and other attributes to the topics that are not added by the default Sandcastle transformations.
• A JavaScript declaration syntax generator that can be used for regular JavaScript as well as Script# projects.
• A Resolve Conceptual Links build component that fixes some bugs in the standard version of the component and also adds some new features.
• A set of cached build data components that cache key information such as comment, reflection index information, and MSDN URLs across builds in order to speed them up.

The custom build components can also be used outside of the help file builder in other custom build scripts and third-party tools as well.

Other Resources

Getting Started
Installation Instructions
Sandcastle Help File Builder Overview
Links to Resources
Version History