|
|
|
[This is preliminary documentation and is subject to change.]
This topic gives an overview of the Sandcastle architecture.
Sandcastle Layers
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 to produce web-ready HTML files as output.
Sandcastle's output can be used as-is by hosting the generated HTML files and their dependencies (namely, CSS 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 or Microsoft Document Explorer. Typically, compiled help files are distributed with the products being documented, or at least made available as a separate download.
Modes of Operation
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.
 Note |
|---|
|
Although built separately, the outputs from the reference and conceptual builds are compatible and are typically combined into a single help file. |
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 Sandastle in reference mode is created by the BuildAssembler tool with a specific configuration. It produces a set of HTML 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 HTML files in the appropriate places; e.g., contents of the <summary> elements appear at the top of the HTML 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 HTML files that are created by transforming the individual MAML files, where one HTML file is created per MAML file. The HTML 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.
Presentation Styles
The presentation styles in Sandcastle contain all of the aesthetic resources that are required to build HTML documentation in different styles. Each presentation style includes a set of XSLT files, XML files, CSS files, and images. The set of XSLT files is executed once for each topic that BuildAssembler processes to produce an individual HTML file as output. Each presentation style can have a different set of XSLT files (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 CSS files and images are referenced by the HTML files that are generated, so technically they are just static output.
