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:
Load reflection data
Load authored comments
Execute an XSL transform
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 generatingAnonymous
October 27, 2007
The DocProject 1.9.0 Release Candidate will contain several bug fixes and some exciting new features