Sandcastle under the hood, part 2

In my previous post, I talked you through the first steps of the Sandcastle build process. So far it’s been more or less simple xsl transforms, but now we’re getting to the fun part – the BuildAssembler.

The BuildAssembler is actually just a small console application that runs an XML document through a configurable pipeline of components. The pipeline is run once for each topic in the manifest. It is sandcastle.config that tells the BuildAssembler which components to apply to the XML document, and in which order they are to be applied. Before running the first topic, each component gets a chance to initialize itself according to the parameters given.

There’s a whole bunch of different components you can use. I’ve compiled a list of them and a short description of what (I think) they do.

Content components

These components are primarily used to add new content to the XML document.

CopyFromFileComponent

Adds the contents of a file to the XML document

CopyFromIndexComponent

Copies specific parts of the contents of one or more XML files to the XML document.
When initializing, this component builds up an index of the set of XML-files which makes the process rather quick. The index is global to the entire process so the same index can be used by multiple CopyFromIndexComponents.

Flow components

Components used for controlling the flow through the pipeline.

ForEachComponent

This component typically contains one or more other components. It applies these contained components on each node in a node list given by an xpath expression.

IfThenComponent

Evaluates an xpath expression. Depending on the result it either applies the components in the then-branch or the else-branch.

SwitchComponent

Evaluates an xpath expression. Depending on the value it applies the appropriate components in the correct case-branch.

Output components

DisplayComponent

Dumps the contents of the current XML document to the console. Check out a previous post to see how you can take advantage of this!

SaveComponent

Saves the contents of the current XML document to a file.

ValidateComponent

Validates the current document against one or more XML Schema (xsd) files. Any errors are written to the log (usually just the console).

Transformation components

These components do the main workload. They resolve references, replace nodes, transform, create new structures et.c.

ResolveReferenceLinksComponent

Resolves links to other pages in the current project or to pages in external documents. There are three kinds of links available; Local (within the current project, creates <a href= style links), Index (to other MShelp documents, creates MSHelp-style links) and None (just text, doesn’t produce a link at all).

SyntaxComponent

Used together with one or more SyntaxGenerators (there is one for each main language) to create syntax strings for the current class/method/property et.c. The syntax generators actually seem complex enough to warrant an entire article of their own.

SharedContentComponent

Replaces <include> and <includeAttribute> elements with contents found in external xml files (like shared_content.xml and reference_content.xml). The content can also take parameters in the standard form expected by string.Format, so if the item in shared_content.xml looks like this:

<item id="artPath">..\art\{0}</item>

Then a node like this:

<img>
<includeAttribute name="src" item="artPath">
<parameter>LastChild.gif</parameter>
</includeAttribute>
</img>

Will be transformed into this:

</img src="..\art\LastChild.gif" temp_src="..\art\LastChild.gif">

TransformComponent

Simply applies an xsl transform to the document.

Other components

These are components that I’m not really sure about how they work since they aren’t used in the example given.

ExampleComponent

Seems to be used to include a set of common sample code snippets. Not sure, but I think it looks for comment links with the following signature:
<ddue:codeReference>

ResolveArtComponent

Seems to be used for linking to common image files?

ResolveConceptualLinksComponent

Looks quite similar to the ResolveReferenceLinksComponent, and I’m not really sure about the difference.

Well, this turned out to be a rather long post. In the next session, I’ll explain how the sandcastle.config is currently wired to build the sample project

Update

Also check out Part 1 and Part 3

Coding Insomnia