General Information
Sandcastle is not a single executable program but is actually a set of command-line programs and transformations that are executed in a specific sequence to produce a set of files that can be used to create a help file. It is extremely flexible and offers many configurable features and the build process can be changed depending upon the desired output format and presentation style.
As the tools are command-line based, they can be used in various ways such as in batch files, MSBuild projects, and PowerShell scripts. One downside to its command-line based nature and the flexibility it offers with its various configuration files and presentation styles is a steep learning curve. Using the tools in their native form can be a daunting process so a good front end that hides the various details can greatly simplify the process of using them.
It is highly recommended that you use an open source front end such as the Sandcastle Help File Builder that provides both a standalone GUI as well as Visual Studio integration. It provides the usual project management options and also many more features that can be used to produce better looking help files and to author conceptual help topics. It also hides the complexity of the Sandcastle tools and lets you focus on the task of authoring the help content.
Sandcastle produces two types of help topic, each using a different build process. The results can be combined into a single help file.
Conceptual Content - This topic is an example of conceptual content. It is written using Microsoft Assistance Markup Language (MAML) and is used to create topics for general conceptual information, walkthroughs, how-tos, etc. For more information about MAML and how to use it, see the Sandcastle MAML Guide that is available for installation along with the Sandcastle tools.
API Reference Content - Reference content is generated by using reflection to generate information about one or more managed assemblies, the types it contains, and their members and combining that information with the related XML comments extracted from the source code. This produces topics with a format similar to those you see on Microsoft help websites. For more information about XML comments and how to use them, see the Sandcastle XML Comments Guide that is available for installation along with the Sandcastle tools.
As noted above with regard to API reference content, Sandcastle is primarily for use in documenting managed code assemblies that utilize the standard .NET Framework, Silverlight, the .NET Portable framework, or the .NET for Windows Store Apps framework. However, if you can produce a reflection information file for other API types such as a JavaScript library, it is possible to document them as well. For example, plug-ins exist for the Sandcastle Help File Builder that allow you to document JavaScript libraries and XML schemas. Currently, there is no means of documenting unmanaged native code assemblies with Sandcastle. However, if information about the unmanaged API could be converted to a reflection information file, it would be possible to produce a help file.
It is important to note that Sandcastle itself does not generate the end result, a compiled help file such as a Help 1 file (CHM), an MS Help Viewer file (MSHC) file, or an Open XML document. Instead, it relies on third-party tools such as the Help 1 compiler in the HTML Help Workshop or the third-party front ends to compress the content into an MS Help Viewer archive or Open XML document. The HTML output by Sandcastle is ready to use for website output but it lacks a front end to display the table of content in any meaningful way and does not provide for searching or a keyword index. Third-party tools such as the Sandcastle Help File Builder can fill these gaps for you.