Product Overview: Sandcastle and Sandcastle Help File Builder
Introduction
Sandcastle is a documentation generator tool developed by Microsoft, designed to automate the creation of MSDN-style code documentation from .NET assemblies and XML documentation comments. To enhance its usability, the Sandcastle Help File Builder (SHFB) was created to provide a more user-friendly interface and additional features.
What Sandcastle Does
Sandcastle is a set of command-line programs, configuration files, build components, and XSLT files that work together to convert XML-based documentation into help topics. It generates web-ready, XML-compliant HTML documentation from .NET assemblies and XML documentation files produced by compilers. This tool is primarily used for documenting managed code assemblies that utilize the .NET Framework, Silverlight, the .NET Portable framework, or the .NET for Windows Store Apps framework.
Key Features of Sandcastle
- Documentation Generation: Sandcastle produces two types of documentation: conceptual (user) documentation and reference documentation. Conceptual documentation is written using Microsoft Assistance Markup Language (MAML) and includes topics such as walkthroughs, how-tos, and troubleshooting guides. Reference documentation is generated automatically from reflection data and XML documentation comments, providing detailed information about managed APIs.
- Flexibility and Customization: The tool is highly flexible, allowing customization through various configuration files and presentation styles. It can be integrated into batch files, MSBuild projects, and PowerShell scripts.
- Build Components: Sandcastle includes several build components such as MrefBuilder, XslTransform, and BuildAssembler, which perform tasks like reflecting against managed assemblies, applying XSL transformations, and generating in-memory data indexes.
Sandcastle Help File Builder (SHFB)
To address the complexity and steep learning curve of using Sandcastle directly, the Sandcastle Help File Builder was developed.
Key Features of Sandcastle Help File Builder
- User-Friendly Interface: SHFB provides a standalone graphical user interface (GUI) and Visual Studio integration, making it easier to manage and build help files. This interface hides the complexity of the underlying Sandcastle tools, allowing users to focus on authoring help content.
- Project Management: The tool offers project management options, including creating new projects, saving projects, and managing files through a Project Explorer window. It also includes features for building help files, viewing log files, and viewing compiled help in various formats.
- Automated Build Process: SHFB automates the build process, providing features similar to those of NDoc. It supports both conceptual and API reference topics, combining the XML comments from source code with the syntax and structure of the types acquired through reflection.
- Customization and Configuration: The GUI allows users to edit properties that control the features and appearance of the compiled help file. It includes dropdowns for configuration and platform options, which are used to specify default values when extracting information from Visual Studio project documentation sources.
Additional Benefits
- Integration with Visual Studio: SHFB offers a Visual Studio integration package, enabling users to create and manage help projects entirely within the Visual Studio environment.
- Community Support: There are community-developed GUI tools and plugins available that extend the functionality of Sandcastle, such as support for documenting JavaScript libraries and XML schemas.
In summary, Sandcastle and the Sandcastle Help File Builder provide a powerful and flexible solution for generating high-quality documentation for .NET applications, making it easier for developers to create and manage comprehensive help files.