Vishful thinking…

Documentation using Sandcastle – Part 1

Posted in Uncategorized by viswaug on September 26, 2007

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

 Sandcastle uses three separate tools to achieve its end goal. The three tools used by Sandcastle are

  • MrefBuilder
  • XslTransform
  • BuildAssembler

 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.

<apis>

        <api id=”cer” />

                <!– many child elements containing reflection data on cer –>

        </api>

<!– more api elements –>

</apis>

 

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 …

One Response

Subscribe to comments with RSS.

  1. Richard Watson said, on August 3, 2010 at 1:59 pm

    Do anyone know how to build help using SandCastle such that references to ESRI objects, e.g. IMap, appear as links to ESRI’s online help? What I want is the same level of functionality which occurs when Microsoft objects are referenced in XML comments.


Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: