Introduction
Sandcastle is Microsoft's new tool for generating MSDN-style documentation from your .NET assemblies and in-code XML comments. More info here^. On 29 July 2006, they released the CTP, and the blog soon followed up with an 11-step manual process to generate the CHM file using their test class. It seemed easy enough to create a BAT script to accomplish all this automatically, however, there were a few issues that made this non-trivial. I've come up with a BAT script to automate this process, as well as a configuration utility.
Advantages
- Multiple assemblies supported.
- Simply re-run the BAT script when you need to recompile your documentation (no need to run a GUI and re-select assembly/comments files).
- Doesn't overwrite help project if it exists (so you can modify it in the Help workshop - especially handy for setting the default page so you don't get the ! icon when you open the CHM).
- Option to keep or delete the working files after compiling your CHM.
- The configuration utility automatically fills the XML path and the CHM path when you select your assembly. (So long as the XML file exists and the CHM field is empty.)
Disadvantages
- BAT script doesn't have any nice logging or friendly messages or error handling.
Configuration Utility
Browse for your .NET assembly. If an XML file with the same path exists, the XML path is automatically set. The CHM path is also automatically set using the same path, unless you specified a CHM path already. If you check the Delete working files checkbox, the "output" folder containing the HTML help project, HTML files, art files etc., will be deleted by the batch script.
Click Create BAT, which will customise the BAT script and save it to the same folder that you selected for the CHM file (filename: sc_compile.bat). And the customised sandcastle.config file will also be saved to this folder (with the correct paths as per the manual setting in template.xml). Now, just double click sc_compile.bat and wait for it to work its magic. You should end up with the CHM file that you specified.
Note: You can move the sc_compile.bat and sandcastle.config to another folder if you want - the BAT script will run from anywhere. When it runs, it creates an output folder which is where all the working files are generated/copied to. If you have checked the checkbox in the configuration utility, then this folder is automatically deleted once the CHM compile is complete.
What's this template.xml?
Well, I'm not a big fan of XSLT for simple template transformations. And the String.Format() can be really confusing with various {0}..{n} scattered throughout the source string. A few years ago, I created a class to perform replacements by processing replacement variables which correspond to element names.
In template.xml, you can edit two settings that are not editable using the configuration utility. They are: SandCastleInstallPath and HtmlHelpInstallPath. If you select different install paths for Sandcastle or HTML Help, you will need to change these values manually.
Two small excerpts from template.xml:
<AssemblyPath>C:\test_sc\assembly here\ScrollingGrid.dll</AssemblyPath>
<XmlCommentsPath>C:\test_sc\assembly here\ScrollingGrid.xml</XmlCommentsPath>
MRefBuilder "{$AssemblyPath$}" /out:reflection.org
copy "{$XmlCommentsPath$}" comments.xml
As you can guess, {$AssemblyPath$} gets replaced with the AssemblyPath node's text. The class to perform this replacement functionality is included in the source.
Requirements
- Sandcastle
- HTML Help 1.4 SDK
- .NET framework 2.0
BAT Script
This is the latest edition of the BAT script:
Text has been wrapped in the snippet below to avoid page scrolling.
if not exist output mkdir output
cd output
if not exist comments mkdir comments
del comments\*.xml
copy "C:\Inetpub\wwwroot\_dev\ScrollingGrid\bin\asb\*.xml" comments
MRefBuilder "C:\Inetpub\wwwroot\_dev\ScrollingGrid\bin\asb\*.*"
/out:reflection.org
XslTransform "C:\Program Files\Sandcastle\ProductionTransforms\AddOverloads.xsl"
reflection.org | XslTransform "C:\Program Files\Sandcastle\
ProductionTransforms\AddGuidFilenames.xsl"
/out:reflection.xml
XslTransform "C:\Program Files\Sandcastle\ProductionTransforms\
ReflectionToManifest.xsl" reflection.xml
/out:manifest.xml
if not exist html mkdir html
if not exist art mkdir art
if not exist scripts mkdir scripts
if not exist styles mkdir styles
copy "C:\Program Files\Sandcastle\Presentation\art\*" art
copy "C:\Program Files\Sandcastle\Presentation\scripts\*" scripts
copy "C:\Program Files\Sandcastle\Presentation\styles\*" styles
BuildAssembler /config:../sandcastle.config manifest.xml
XslTransform "C:\Program Files\Sandcastle\ProductionTransforms\
ReflectionToChmContents.xsl" reflection.xml
/arg:html="html" /out:"Test.hhc"
if not exist help_proj.hhp copy "C:\Program Files\Sandcastle\
Presentation\Chm\test.hhp" help_proj.hhp
"C:\Program Files\HTML Help Workshop\hhc.exe" "%CD%\help_proj.hhp"
@copy "Test.chm" "..\doc.chm"
@cd ..
REM @rd /s /q output
@pause
As you can see, all the paths are configured. The tricky part while developing this was figuring out what customisation sandcastle.config required to be able to find its assemblies and XML files and generate the HTML files to the correct directory. There was no documentation about this at the time, nor any documentation about the arguments.
Note: Sandcastle installation adds C:\Program Files\Sandcastle\ProductionTools to the Windows PATH environment variable. However, if you have an issue running MRefBuilder, XslTransform, and BuildAssembler, you can convert these calls to absolute paths (just update template.xml).
Conclusion
I think Microsoft have done a good job on the interface of the generated HTML files (i.e., DHTML capabilities etc.), which is the main thing that piqued my interest in this release. I haven't seen any good quality MSDN-style documentation from other documentation compilers - but I must admit I haven't experimented with the latest version of NDOC.
Updates
- Link label to open output directory. (5 Aug 2006)
- Now supports wildcards (i.e., class documentation for multiple assemblies in the same CHM file). As you can see in the screenshot, just specify *.* as the assembly file, and *.xml as your comments file. The BAT script and sandcastle.config have been updated to support this, and it is working well for me. (2 Aug 2006)
