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 (2)

  1. Recently I've been receiving more feedback than usual about the addition of non-API topics when generating

  2. The DocProject 1.9.0 Release Candidate will contain several bug fixes and some exciting new features

Skip to main content