Sandcastle Configuration (sandcastle.config)

  • Article

Overview

Sandcastle builds documentation for any managed class libraries. Sandcastle requires the following inputs:

  • A set of managed assemblies (.dlls or .exes) to document

  • The set of assemblies on which the operation of those assemblies depend (aka dependencies)

  • XML comment files like those generated from /// comments using the /doc option. XML documentation comments can be added to your source files ( .cs or .vb or .h/ .cpp). In Visual Studio 2005, the C# (csc.exe), VB (vbc.exe), and C++ (cl.exe) compilers all support XML documentation comments using the /doc:assembly.xml switch. In previous versions of the .NET Framework only C# supported XML documentation comments. For more information on authoring documentation comments, click here.

The output of Sandcastle consists of HTML pages. These pages can be packaged in a CHM file using the HTML Help Workshop tools.

The Sandcastle process uses three executables:

  • MRefBuilder: Reflects over managed assemblies to produce an XML-formatted reflection information file.

  • BuildAssembler: Collates information from comment files and reflection information files into a set of HTML pages.

  • XslTransform: Applies XSL transforms to XML files. This executable is used to generate and manipulate auxiliary data files.

In addition to these executables, a number of useful XSL transform files and auxiliary data files are provided.

Configuration

The sandcastle.config file specifies the steps that BuildAssembler takes to build each topic and the data sources used in those steps. Whether you do something as simple as change the name or location of an input file, or something as complex as adding a new step of your own, you will need to develop a basic familiarity with this file.

The steps are specified as <component> elements under the <components> root element. The configuration data used by each component is represented as XML data under the <component> tag.

The components used in the Sandcastle stack are:

  1. Create a skeleton XmlDocument to store topic data.

  2. Load reflection data for the topic from the reflection.xml file.

  3. Copy in reflection data for namespace (in type and member topics) and types (in a member topic) that contain the API.

  4. Generate syntax blocks for the API.

  5. Copy in authored comments for the topic from the comments file.

  6. Copy in reflection data and authored summaries for members (in a type topic) or types (in a namespace topic).

  7. Apply a transform to the topic to generate an HTML page.

  8. Resolve any references to localizable shared content.

  9. Resolve any references that link to other topics.

  10. Save the result to a file.

Many of these components read data from external files. You may want to change the files that are read, or add new ones.

If you are a developer, you can create and use your own component. A component is an implementation of the abstract BuildComponent class, defined in BuildAssembler.exe. The only members required are a constructor that accepts an XPathNavigator, from which the component should read its configuration data, and an Apply method that accepts an XmlDocument representing the topic and a string representing the topic ID. Add your component to the stack by adding a <component> tag with assembly and type attributes that point to your component. Using the configuration data loaded in its constructor, your component can do anything it wants to the topic XmlDocument.

Notice that the reflection data step reads the reflection.xml file that you generated, and also reflection data files in the cpref_reflection directory to get reflection data for .NET Framework assemblies. (You could generate these files yourself by running MRefBuilder on the assemblies in your .NET Framework installation directory.) Notice that you can specify multiple <data> elements to read data from multiple sources, and use wildcards in the files attribute to specify multiple source files using each <data> element. If the assembly you document depends on types defined in other assemblies, you may want to add reflection data files for those assemblies here.

Notice that the copy comments step reads the comments.xml file that you generated, and also comment files in the .NET Framework directory that contain authored summaries of the APIs in the .NET Framework assemblies. (These files are installed by the .NET Framework SDK, so if you want these summaries to appear for the APIs that your types inherit from .NET Framework types, you will need to install the .NET Framework SDK, or at least copy those files from a .NET Framework SDK installation into a directory that you reference here.)

Notice that the transform step loads its topic transform from a file in the Presentation\transforms directory. If you want to change the look-and-feel of a topic, you will need to make changes to that transform.

Notice that the resolve shared content step reads shared content elements from files in the Presentation\content directory. If you want to change the names of sections, headings, etc. that appears in topics (for example, in order to localize them into a non-English language) you will need to make changes to those files.

Notice that the resolve reference links step requires topic data files in order to correctly render links. If you add a topic data file to the reflection step configuration, you should add it here also.

Finally, notice that the path to which a topic file is saved is constructed via an XPath expression in this component’s configuration. If you want to save topic files to a different location, make that change here.

 

I will post new blogs about BuildAssembler and MrefBuilder.