BuildAssembler Configuration

In my previous blogs I have discussed the architecture of BuildAssembler, a configurable build component stack of Sandcastle. As each topic is build, it is represented as an in-memory XML document. The document is passed through a stack of build components, each of which can act on the document in any way. The component stack is specified in Sandcastle.config file, and the set of topics to be generated is specified in a manifest. A simple component stack that might be used to generate API reference documentation is shown below:

  1. Load reflection data

  2. Load authored comments

  3. Execute an XSL transform

  4. Save the document

We shipped Orcas Beta 1 Library (scheduled to be live at MSDN on APril 18th) using Sandcastle. We currently maintain four configuration files for each presentation layer:

· Conceptual.config: for conceptual projects. We do not ship this config with Sandcastle CTP.

· Sandcastle.config: for external managed reference projects. We ship this config with Sandcastle CTP.

· Reference.config: for internal managed reference projects that inherit APIs from other projects. We do not ship this config with Sandcastle CTP.

· Reference-core.config: for self-contained internal managed reference projects (e.g. fxref). We do not ship this config with Sandcastle CTP.

This table below describes the steps specified by each configuration file and the external data sources on which each step draws.

 

The steps used in each scenario are (reference and reference-core are the same in this table):

 

Step

Description

Conceptual

Sandcastle

Reference

Copy skeleton

Create skeleton XML document.

X

X

X

Topic API data

Copy in API data for the topic API.

 

X

X

Container API data

Copy in API data for the topic API’s container (e.g. namespace data for type APIs).

 

X

X

Event handler API data

Copy in API data for the handler API associated with an event.

 

X

X

Parameter API data

Copy in API data for the topic API’s parameter types (e.g. argument types of a method).

 

 

X

Generate syntax

Call syntax generators to create syntax blocks.

 

X

X

Comments

Copy in comments for the topic API.

X

X

X

Snippet resolution

Resolve code snippets.

X

 

X

Members

Copy in API data and comments for members (e.g. type data for namespace APIs).

 

X

X

Token resolution

Resolve tokens.

X

 

X

Metadata

Copy in project & topic metadata

X

 

X

Intellisense

Write out intellisense for the topic API.

 

 

X

Transform

Apply XSLT to produce HTML.

X

X

X

Art link resolution

Resolve art links.

X

 

X

Shared content resolution

Resolve shared content.

X

X

X

Conceptual link resolution

Resolve conceptual links.

X

 

X

Reference link resolution

Resolve reference links.

X

X

X

Save

Save the resulting file.

X

X

X

 

The associated data sources are (reference and reference-core are not the same in this table):

 

Source

File(s)

Conceptual

Sandcastle

Reference

Reference-core

Local comments (/// format)

Comments.xml

 

X

 

 

External comments (/// format)

%SystemRoot%\Microsoft.NET\Framework\*\*.xml

 

X

 

 

Local comments

(DdueXml format)

DdueXml

X

 

X

X

External comments (DdueXml format)

%DXROOT%\Data\DdueXml\*.xml

 

 

X

 

Local topic metadata (XmlComp format)

XmlComp\*.xml

X

 

 

 

External topic metadata (XmlComp format)

%DXROOT%\Data\XmlComp\*.xml

X

 

X

X

Local API data

Reflection.xml

 

X

X

X

External API data

%DXROOT%\Data\Reflection\*.xml

 

X

X

 

Snippets

%DXROOT%\Data\CodeSnippet.xml

X

 

X

X

Tokens

%DXROOT%\Data\Tokens.xml

X

 

X

X

Art

%DXROOT%\Data\Art

X

 

X

X

Shard content

%DXROOT%\Presentation\*\Content\*.xml

X

X

X

X

Conceptual project metadata

ExtractedFiles\*.ContentMetadata.xml

X

 

 

 

Reference project metadata

SupportFiles\*Metadata.xml

 

 

X

X

 

Hope this helps users to understand the Sandcastle.config file shipped with Sandcastl CTPs. Please inform me of any discrepancies you notice.

 

Anand..