Journey From NDoc To SandCastle

NDoc was Source Forge tool for generating MSDN style documentation based on XML comments in your .NET 1.0 or 1.1 code. Now with the evolution of 2.0 XML Comments with "///" no revised NDoc version is available till date.

Microsoft has stepped in an provided SandCastle, which allows you to generate documentation and help files based on your .NET 2.0 code. It is still in CTP, but has the following features:

“Sandcastle produces accurate, MSDN style, comprehensive documentation by reflecting over the source assemblies and optionally integrating XML Documentation Comments. Sandcastle has the following key features:

• Works with or without authored comments
• Supports Generics and .NET Framework 2.0
• Sandcastle has 2 main components (MrefBuilder and Build Assembler)
• MrefBuilder generates reflection xml file for Build Assembler
• Build Assembler includes syntax generation, transformation..etc
• Sandcastle is used internally to build .Net Framework documentation“

You can download SandCastle here

Following resources can provide you additional information about Sandcastle:

• Sandcastle Helper
• FAQ
• Sandcastle Visual Studio 2005 Add-In

Creating a Chm build using Sandcastle

Here are the steps to create a Chm build using Sandcastle. Please see the atatchment for the steps in text format.

Prerequisites:

1. .Net Framework 2.0

2. For Chm generation download HTML Help Workshop - http://msdn.microsoft.com/library/default.asp?url=/library/en-us/htmlhelp/html/hwMicrosoftHTMLHelpDownloads.asp

How do Reference Build From /// Comments using Sandcastle V2.0:

Sandcastle can read authored triple-slash comments embedded in source files.

1. Sandcastle by default is installed at c:\Program files\Sandcastle. Open a command prompt and type the following:

cd \Program Files\Sandcastle\Examples\Sandcastle

In this directory, you will find only a single C# file called test.cs under Examples\sandcastle directory.

2. Begin by compiling the C# file and extracting the /// comments.

csc /t:library /doc:comments.xml test.cs

3. This creates not only test.dll, but also comments.xml file that contains the extracted /// comments

4. Next, run MRefBuilder:

MRefBuilder test.dll /out:reflection.org

5. Transform the output

For building 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

6. Generate a topic manifest

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

7. Create an output directory structure

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

8. Run BuildAssembler using the sandcastle component stack (Note: We are providing VS 2005 transforms under Presentation/VS2005 folder and the transforms shipped with the previous versions under Presentation/Prototype folder. For building VS2005 format please use sandcastle.config file from C:\Program Files\Sandcastle\Presentation\vs2005\Configuration folder as it uses shared content from C:\Program Files\Sandcastle\Presentation\vs2005\Content and transforms from C:\Program Files\Sandcastle\Presentation\vs2005\Transforms)

BuildAssembler /config:sandcastle.config manifest.xml

to generate topic files in HTM.

9. Generate HTML help project

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

10. Generate intermediate table of contents

For building using VS2005 transforms please use the following:

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

11. Generate HTML help project information

XslTransform /xsl:..\..\ProductionTransforms\TocToChmContents.xsl toc.xml /out:Output\test.hhc

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

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

hhc output\test.hhp