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. I created the Sandcastle Help File Builder to fill in the gaps and provide some of the missing NDoc-like features that I use most often, as well as provide graphical and command line based tools to build a help file in an automated fashion. Using the help file builder provides the following advantages:
- The GUI interface is almost identical to the NDoc interface so anyone familiar with NDoc should be quite comfortable using it.
- You can import several settings from an existing NDoc project to start a new Sandcastle Help File Builder project.
- You can import the assembly and documentation file information from a Visual Studio 2003/2005/2008 solution or project file to start a new Sandcastle Help File Builder project.
- The builder will automatically locate both Sandcastle and the HTML help compilers by looking 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 builder can produce an HTML 1.x (.CHM) file, an HTML 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.
- There is built-in support for documenting multiple assemblies and producing a single-help file for them. The assemblies to document can be executable (.EXE) or library (.DLL) assemblies.
- The settings are saved in a project file and the help file can be built from within the GUI or you can add a post-build step to a Visual Studio project that runs the command line tool to build it for you using the same project file.
- 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.
- 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, highlight warnings and errors, etc.
- Several of the NDoc features that I use most often 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).
- I have added features to let you control the language of the help file.
- Steps have been taken to make the build process fairly 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 additional content items.
- 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.
- 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.
- 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.
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 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.
- An 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 build scripts and automated tools as well. See the help file supplied with the help file builder for more information on how to use it. A FAQ is included in the help file that should answer most of the common questions and provide solutions to most of the common issues encountered while using it.
Links to Resources
The following resources related to Sandcastle are available: See the Links to Resources topic in the supplied help file for other useful resources. Special thanks to Alessandro Del Sole for featuring the Sandcastle Help File Builder in his Italian language book Programming with Visual Basic 2005 Beyond the Code.
|
