Share via

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.

Comments

  • Anonymous
    August 07, 2006
    I managed to build a .chm help for my class libraries. There are two issues:

    1. When I open the .chm, the first page displayed is empty (only a little warning icon is displayed, kindof indicating an error). Can I specify the default page somehow?

    2. There's no index being displayed. Can I turn index generation on?

    Thanks
    KarloX
  • Anonymous
    August 08, 2006
    KarloX,
    We have a fix for both in our next CTP.

    1. The root node is missing in HHP and we have fix.

    2. We are addressing the index generation in our next CTP.

    I expect us to drop a CTP in the next 2 weeks.

    Anand..
  • Anonymous
    August 08, 2006
    Hi.

    We needed to generate documentation for one of our project last week. Not finding any GUI for SandCastle integration into Visual Studio 2005, we created our own that is now freely downloadable from our web site (www.processacademy.ca/news/en/XpertBuildDoc.aspx).

    Thanks for letting us know what you think of it!

    Francis
  • Anonymous
    August 08, 2006
    Awesome work. Thanks a lot guys.
  • Anonymous
    August 09, 2006
    The comment has been removed
  • Anonymous
    August 09, 2006
    The comment has been removed
  • Anonymous
    August 09, 2006
    And one more thing..
    The <list> .. directive doesn't seem to be handeled properly (chm), at least when it occurs within a <remarks> section.

    KarloX
  • Anonymous
    August 10, 2006
    KarloX,
      I posted an addition in the forum on the <list> directive.

    See http://forums.microsoft.com/MSDN/ShowPost.aspx?PostID=622335&SiteID=1
  • Anonymous
    August 10, 2006
    The comment has been removed
  • Anonymous
    August 11, 2006
    I've spent some time playing with Microsoft's solution to build documentation based on XML tags in your code. This post gives a brief recap of what I experienced as well as providing links to help you get started.
  • Anonymous
    August 13, 2006

    I my previous blogs I discussed MrefBuilder and Sandcastle.config in detail. Sandcastle process uses...
  • Anonymous
    August 14, 2006
    I've spent some time playing with Microsoft's solution to build documentation based on XML tags in your code. This post gives a brief recap of what I experienced as well as providing links to help you get started.
  • Anonymous
    August 14, 2006
    Syntax in Sandcastle documentation is generated by SyntaxBuilder. SyntaxBuilder uses the Common Compiler...
  • Anonymous
    August 20, 2006
    Installation and Layout

    Sandcastle CTP can be downloaded from http://www.microsoft.com/downloads/details.aspx?FamilyId=E82EA71D-DA89-42EE-A715-696E3A4873B2&amp;amp;displaylang=en...
  • Anonymous
    April 16, 2007
    The comment has been removed
  • Anonymous
    April 01, 2008
    PingBack from http://copyrightrenewalsblog.info/sandcastle-sandcastle-configuration-sandcastleconfig/