Benefits and Features
This help file was built using the help file builder and demonstrates many of the features that it provides as described in the following sections:
General Benefits and Features
The standalone GUI interface provides a Visual Studio-like project explorer and a set of property pages that let you manage the project settings and edit the files associated with the project. If you are familiar with Visual Studio or third-party integrated development environments like SharpDevelop, you should be able to get up and running fairly quickly. You do not need to know anything about the underlying Sandcastle tools to take advantage of their features.
An extension package is available for Visual Studio 2017 and later that lets you create, manage, and build projects from within Visual Studio. In addition to providing a familiar environment for project management, it also gives you access to the additional features provided by Visual Studio such as source control for your help file projects.
The help file builder can produce an HTML Help 1 (.chm) file, an MS Help Viewer (.mshc) file, an Open XML (.docx) document, a website, and/or markdown content.
The MS Help Viewer output includes a valid help content setup file that can be used to install the content in the help viewer using the Help Library Manager tool. Options are included in the standalone GUI and the Visual Studio package to install and view the content without having to perform those tasks manually.
A Help Library Manager launcher utility is also supplied to ease installation and removal of MS Help Viewer content. This utility is freely distributable for use with your product installers. Sample scripts are generated with the help file that show how to use the tool to install and remove the content.
The website output contains a standard HTML index page. The table of content style varies by presentation style. Older versions use a frame-based layout while newer presentation styles use table of contents elements embedded in each topic. The new style is implemented as HTML and client-side script which is suitable for servers and content delivery networks that do not support ASP.NET or PHP. A full-text index search feature is available as well with support for ASP.NET, PHP, and client-side script implementations.
The project 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 dotnet build, or in a post-build step for a Visual Studio project that runs MSBuild. Support for full Visual Studio integration is also available with the above mentioned extension package.
Visual Studio 2005 and later 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 can only be added natively via the Visual Studio extension package.
The help file builder will automatically locate both Sandcastle and the 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 on 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 an 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 contents such as usage notes, tutorials, etc. Conceptual content is created using Microsoft Assistance Markup Language (MAML).
For backward compatibility, standard HTML files can also be included and merged with the table of contents using a site map file to define their layout. However, note that these features have been deprecated and MAML is the preferred method of adding conceptual content to the help files.
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.
Support is included for the <inheritdoc /> tag which allows you to inherit documentation from base types/members.
Extensibility Using Plug-Ins
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 build engine itself or the Sandcastle tools. 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 in a project (no API content).
Additional Reference Links - Add additional sources of reference links for third-party libraries or online content that does not appear in your help file.
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 when using non-English languages that use a double-byte character set (DBCS).
Output Deployment - Copy the resulting help file to a file share, web server, FTP site, etc.
Table of Contents Exclusion - Used to exclude API members from the table of contents (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.
Extensibility Using Build Components
Build components can be used to extend or alter how the topics are created at build time. This lets you add new features such as code colorization or support for visual elements specific to a particular help file format. The help file builder supplies the following custom build components:
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. This is usable 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 certain compiler generated elements such as default constructors and finalizers.
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.
An API token resolution component that lets you utilize MAML tokens in your XML comments to insert common elements or sections of documentation.
All build components are Managed Extensibility Framework (MEF) components and can be selected for inclusion in your projects. You can also create your own components using the documenation in this help file. There is also support for defining additional language syntax generators used to generate the syntax sections in the API reference topics.
Support for Third-Party Presentation Styles
Sandcastle comes with some standard presentation styles. You can use them as-is or clone them to make modifications to suit your needs. You can also create brand new presentation styles. As with plug-ins and build components, the help file builder allows you to create additional presentation styles that it can use by creating new Managed Extensibility Framework (MEF) components that describes the various parts and how to use them. When found, these additional presentation styles are made available to you in the project's property pages.