Sandcastle and Compact Framework Tutorial

You have just finished a project to build a mobile framework. You now need to produce documentation so you get out NDoc and oops NDoc does not support the 2.0 framework. What to do? How about use Sandcastle, a document compiler from Microsoft.

Per the overview of the Sandcastle download it produces accurate, MSDN style, comprehensive documentation by reflecting over the source assemblies and optionally integrating XML Documentation Comments. Basically it is the Microsoft replacement for Build HTML in VS2003. Sandcastle installs a couple of command line tools used to generate XML and modify it using XSLT. The process is straight forward but requires several steps.

Given that I mostly do Windows Mobile projects I will step through how one can use Sandcastle to build documentaion from Compact Framework source. One feature that makes documentation easier is XML comments. The XML is extracted from the source code during compilation using the /doc flag and into a file. This file is then used by Sandcastle to transform it into HTML or CHM content. The XML comments are optional since Sandcastle includes the ability to build basic documentation using reflection. The XML comments are used to add additional information used for documentation and intellisence.

So the steps briefly are

1. Compile the solution and use the /doc switch.
2. Modify the Sandcastle configuration file to use the generated comment files.
3. Use MRefBuilder to reflect and extract out information from the assemblies.
4. Apply some XSL to transform the XML using XSLTransformation.
5. Build the directory structure for storing the documentation.
6. Use BuildAssembler to pull everything togather from the XML comments, reflection, and manifest.
7. Build the help project and table of contents using XSLTransformation.
8. Optionally convert the HTML into a help CHM file using the Help Compiler (HHC).

Compilation
The first step is to compile the assemblies and executables along with extracting out the XML comments. This is easily done with the compiler or VS2005. The compiler has a switch /doc which turns on extracting the XML comments and the name of the file to put the XML.

As you can see in VS2005 you just need to modify the Build properties of the project. You turn on XML using a checkbox and typing in a file name and location.

Now when you compile the solution or project the XML is extracted out of the code. Then placed in the specified file and location. By default Sandcastle expects the file to be called comments.xml.

Configuration
The next step is to tell Sandcastle where to find the Compact Framework and your XML comment file if any. Sandcastle uses XML to define its configuration and parameters. One of the configuration items tells Sandcastle where to find the comment files you will be embedding in the documentation. By changing "comments.xml" to "MyComments.xml" or even "MyAssembly*.xml" you can specify XML files. If multiple files can be specifically added using additional <data> nodes.

<index name="comments" value="/doc/members/member" key="@name" cache="100">
     <data files="MyComments.xml" />
     <data files="%SystemRoot%\Microsoft.NET\Framework\v2.0.50727\*.xml" />
</index>

MRefBuilder
The next step is to reflect across the assemblies you wish to have documentation generated. MRefBuilder will reflect across the various assemblies to create basic information about them including classes, methods, parameters, properties etc.

MRefBuilder MyAssembly.dll /out:reflection.org

You can also use wildcards for example *.dll. Reflection.org contains XML documentation. This will be used to along with the XML comments to build the documentation. One thing that you might find is that not all assemblies are available. MRefBuilder will need to be told where any Compact Framework assemblies are using /dep switch. You can also mark you references as copy local. This will put all the required assemblies in a single directory.

XSL Transformation First Time
There are several transformations that are required before the final building of the HTML. This includes creating the XML for building the documentation and the manifest. With building the XML you can chose between MSDN or the new prototype documentation format. You can also create your own. You just need to build your own XSL. To build the  topics using VS2005 transforms please use the following:

XslTransform /xsl:"..\..\ProductionTransforms\ApplyVSDocModel.xsl" reflection.org /xsl:"..\..\ProductionTransforms\AddFriendlyFilenames.xsl" /out:reflection.xml

For building using prototype transforms please use the following:

XslTransform /xsl:..\..\ProductionTransforms\ApplyPrototypeDocModel.xsl reflection.org /xsl:..\..\ProductionTransforms\AddGuidFilenames.xsl /out:reflection.xml

To build the manifest use

XslTransform /xsl:..\..\ProductionTransforms\ReflectionToManifest.xsl  reflection.xml /out:manifest.xml

Build Directory Structure
One last step before building the HTML. That is creating the directory structure. Again the command you use will depend on the type of documentation you are building. For building using VS2005 transforms please use the following:

call ..\..\Presentation\vs2005\copyOutput.bat

For building using prototype transforms please use the following:

call ..\..\Presentation\Prototype\copyOutput.bat

BuildAssembler
This step will take the XML Comments and XML to build the topics and index using the BuilderAssembler.

BuildAssembler /config:sandcastle.config manifest.xml

The directory structure is now populated with HTML. You can put this up on a website.

Help Project and Compilation
This step will take the HTML and build a help file. This single file can then be deployed rather than a set of HTML files.

The first step in building the Help project file use

XslTransform /xsl:..\..\ProductionTransforms\ReflectionToChmProject.xsl reflection.xml /out:Output\test.hhp

Next generate intermediate table of contents for using VS2005 transforms use the following:
XslTransform /xsl:..\..\ProductionTransforms\createvstoc.xsl reflection.xml /out:toc.xml

For building using prototype transforms use the following:
XslTransform /xsl:..\..\ProductionTransforms\createPrototypetoc.xsl reflection.xml /out:toc.xml   

To generate the HTML help project information and index
XslTransform /xsl:..\..\ProductionTransforms\TocToChmContents.xsl toc.xml /out:Output\test.hhc

XslTransform /xsl:..\..\ProductionTransforms\ReflectionToChmIndex.xsl reflection.xml /out:Output\test.hhk

Run hhc (HTML Help 1.x Compiler) to generate Chm and compile the Sandcastle target files into a CHM file.

hhc output\test.chm

Hopefully, you will find Sandcastle useful for building documentation from the source code.