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..

Comments

• Anonymous
  July 10, 2007
  Recently I've been receiving more feedback than usual about the addition of non-API topics when generating

• Anonymous
  October 27, 2007
  The DocProject 1.9.0 Release Candidate will contain several bug fixes and some exciting new features