Documentation using Sandcastle – Part 1
I recently successfully created the code documentation for our projects using Sandcastle. Sandcastle is a documentation compiler for managed class libraries. It helps generate documentation for your .NET projects in a familiar MSDN format. Sandcastle can be configured to generate documentation in different styles. I created our documentation in the VS2005 format and couldn’t find too much help in creating help in custom styles. Sandcastle does ship with a couple of other documentation styles like ‘prototype’ and ‘hana’. Sandcastle is still in CTP and has not yet moved to RTM yet. So, the documentation is still mostly missing thus making it harder to customize using Sandcastle in your build process.
The compilation of the documentation in Sandcastle happens in a series of steps chained together to produce the desired end result. The figure shown below sheds more light into the steps that are involved in the process.
Sandcastle uses three separate tools to achieve its end goal. The three tools used by Sandcastle are
All three executables can be found in the “ProductionTools” folder under the Sandcastle installation path. A new user environment variable called ‘DXROOT’ will be added to your machine after the Sandcastle installation. So if you don’t know where Sandcastle is installed just execue ‘echo %DXROOT%’ at the command prompt. The function of the aforementioned tools are as follows
MRefBuilder – This executable uses CCI (Common Compiler Infrastructure) to generate reflection metadata in a XML format for the specified DLLs. In other words, it outputs a file containing information in XML format on all the Types in the assembly. The schema of the generated file is quite complicated but it is essentially a list of ‘api’ elements.
<api id=”cer” />
<!– many child elements containing reflection data on cer –>
<!– more api elements –>
XslTransform – This executable applies XSL transformations to XML files. This is a general purpose utility that takes in a XSL file and a XML file and produces an output file which is the result of applying the supplied XSL file transformations to the supplied XML file.
BuildAssembler – This executable is the core engine behind Sandcastle. It collates information from the comment files generated by the .NET compiler and the reflection information files from MRefBuilder and XslTransform into a set of HTML pages. BuildAssembler controls the component stack at the center of Sandcastle. The component stack that will be executed by the BuildAssembler should be passed in to it as a configuration file argument. The configuration file ‘sandcastle.config’ used for the VS2005 style documentation can be found in the ‘Presentation\vs2005\configuration’ folder under the Sandcastle installation path.
More to come …