Architecture

This topic gives an overview of the Sandcastle architecture.

• Sandcastle Layers
• Modes of Operation
  • Reference Mode
  • Conceptual Mode
• Presentation Styles

At a high level, Sandcastle can be seen as a set of tools that transforms raw input into documentation output.

Inputs of various types are supported such as managed assemblies and raw XML documentation files, which are typically compiler-generated along with the assemblies, as well as MAML topics and additional content such as images and code snippets. With this input, Sandcastle performs a highly configurable set of transformations using a presentation style to produce web-ready HTML files or other file formats as output.

Sandcastle's output can be used as-is by hosting the generated HTML files and their dependencies (namely, CSS, scripts, and images) on a web server. Alternatively, and more common, the generated HTML files can be passed as input to help compilers to produce compiled help in various forms. Compilers are additional tools (downloaded separately) that aggregate all of the HTML files produced by Sandcastle to create compiled help files. These are files that can be downloaded and viewed in a special desktop application such as the HTML Help Viewer, Microsoft Document Explorer, or Microsoft Help Viewer. Typically, compiled help files are distributed with the products being documented, or at least made available as a separate download.

Other presentation styles can be created to produce non-HTML output as well. For example, there is a presentation styles that outputs markdown content suitable for GitHub wikis and another that produces an Open XML document that can be opened by Microsoft Word or Open Office.

There are two modes of operation supported by Sandcastle: Reference and Conceptual. The differences between them can be found in both the input and output of Sandcastle. To provide a quick definition of each, consider reference documentation to provide information about the physical properties of a managed library or application, such as the actual namespaces, types, members and method arguments, and consider conceptual documentation to provide instructional information about the overall design and conceptual properties of a managed library or application, such as how to accomplish specific usage scenarios and providing an in-depth analysis of specifically complex APIs. More distinctions between the two modes can be found in their corresponding sections below.

Reference Mode

To produce reference documentation, Sandcastle requires managed assemblies as input. The MRefBuilder command-line tool is used to analyze the physical properties of the assemblies, as well as their dependencies, ultimately producing an XML reflection file that becomes input for the next steps of the process. This XML reflection file contains all of the information that is required to document the physical properties of the input assemblies.

Sandcastle also accepts XML documentation files as input. XML documentation files are typically generated by code compilers from the triple-slash (C#) or triple-apostrophe (VB) comments found in source code files, at the same time that their corresponding assemblies are compiled. XML documentation files contain specific identifiers that allow Sandcastle to correlate XML documentation for each API to the same API in the XML reflection file that is produced by MRefBuilder. Additionally, reference mode supports shared inputs of various types such as images and code snippets to be included in the documentation.

The output of Sandcastle in reference mode is created by the BuildAssembler tool with a specific configuration. It produces a set of files that document the physical structure of the XML reflection file (generated by MRefBuilder) passed in as input. XML documentation comments that are discovered during the process are also injected into the files in the appropriate places; e.g., contents of the <summary> elements appear at the top of the file, while <remarks> contents appear after the syntax section.

Sandcastle also automatically generates a table of contents (TOC) and a keyword index based on the XML reflection file. Each auto-generated API topic also includes appropriate hyperlinks. Typically, pseudo-topics are automatically generated as well; e.g., a topic containing a list of all the types in a particular namespace, and another topic containing a list of all properties in a particular type, etc.

Conceptual Mode

To produce conceptual documentation, Sandcastle depends on a special XML schema called Microsoft Assistance Markup Language (MAML). The input to Sandcastle in conceptual mode must be a set of XML documentation files written against the MAML schema. XML companion files can be provided as input to specify metadata for each MAML topic; e.g., index keywords. Additionally, conceptual mode supports shared inputs of various types such as images and code snippets to be included in the documentation.

The output of Sandcastle in conceptual mode is created by the BuildAssembler tool with a specific configuration. It produces a set of files that are created by transforming the individual MAML files, where one output file is created per MAML file. The files display the data in each MAML topic according to the document type of that topic; e.g., all How-To topics will have an introduction and at least one procedural section that contains an ordered list of steps for the reader to follow. Most, but not all MAML topics also contain a See Also section at the bottom. Special MAML document types, such as Glossary, use a very different type of transformation from the other document types.

It is up to the author to specify a table of contents (TOC) in conceptual mode. Likewise, a keyword index is not automatically generated, so it is the author's responsibility to specify relevant keywords for each MAML topic using an XML companion file.

The presentation styles in Sandcastle contain all of the aesthetic resources that are required to build documentation in different styles. Each presentation style includes a code-based transformation, XML files containing localizable shared content, and other supporting files such as CSS files, images, scripts, etc. The set transformation is executed once for each topic that BuildAssembler processes to produce an individual HTML or other file type as output. Each presentation style can have a different set of transformations (although usually similar in many ways); therefore, each presentation style also must provide a custom configuration for the BuildAssembler tool. The XML files contain look-up information, such as localizable textual content. The other supporting files such as CSS files and images are referenced by the generated files so technically, they are just static output.

Other Resources