Click here to Skip to main content
Click here to Skip to main content
Go to top

Sandcastle CHM-compile BAT script and configuration utility

, 5 Aug 2006
Rate this:
Please Sign up or sign in to vote.
Create MSDN-style class documentation CHM files for your assemblies using Microsoft Sandcastle CTP with this configuration utility and BAT script.

Screenshot

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

  1. Sandcastle
  2. HTML Help 1.4 SDK
  3. .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)

License

This article has no explicit license attached to it but may contain usage terms in the article text or the download files themselves. If in doubt please contact the author via the discussion board below.

A list of licenses authors might use can be found here

Share

About the Author

Ashley van Gerven

Australia Australia
Ash is a C# developer (MCAD) with a background developing e-commerce and content management solutions. His current role includes working with VOIP systems, integration and maintenance of business and billing apps. His personal projects include the ScrollingGrid web control to enable cross-browser freeze-header 2-way scrolling of DataGrids. His other interests include travel, cinema, Squash, photography, Muay Thai.

Comments and Discussions

 
NewsAnother solution PinmemberVictor Blomberg29-Apr-07 12:41 
QuestionError - Not able t o copy ".output\test.hhc" PinmemberkidambiN19-Sep-06 15:49 
AnswerRe: Error - Not able t o copy ".output\test.hhc" PinmemberAshley van Gerven19-Sep-06 20:27 
GeneralRe: Error - Not able t o copy ".output\test.hhc" PinmemberkidambiN20-Sep-06 5:17 
AnswerRe: Error - Not able t o copy ".output\test.hhc" Pinmemberandyqp12-Oct-06 4:38 
GeneralNDoc alpha vs. Sandcastle PinmemberMirkoMaty8-Aug-06 22:08 
GeneralRe: NDoc alpha vs. Sandcastle PinmemberEric Woodruff9-Aug-06 5:07 
GeneralRe: NDoc alpha vs. Sandcastle PinmemberJoel Thoms5-Sep-06 12:26 
GeneralRe: NDoc alpha vs. Sandcastle PinmemberJamie Nordmeyer24-Oct-06 6:43 
GeneralVisual Studio 2005 Sandcastle Add-In [modified] Pinmembermystic7004-Aug-06 1:52 
QuestionRe: Visual Studio 2005 Sandcastle Add-In PinmemberGfw8-Aug-06 3:40 
AnswerRe: Visual Studio 2005 Sandcastle Add-In Pinmembermystic7008-Aug-06 7:57 
GeneralRe: Visual Studio 2005 Sandcastle Add-In PinmemberGfw8-Aug-06 8:02 
GeneralNice Work PinmemberM Harris2-Aug-06 19:07 
Generalrepath issues Pinmemberdalkema1-Aug-06 4:03 
GeneralRe: repath issues PinmemberAshley van Gerven1-Aug-06 4:41 
GeneralNice work Pinmemberluis de santiago31-Jul-06 23:03 
GeneralRe: Nice work PinmemberAshley van Gerven31-Jul-06 23:22 
GeneralException Pinmemberhelpsoft.ru31-Jul-06 19:45 
GeneralYou need to copy files from Demo zip PinmemberAshley van Gerven31-Jul-06 21:21 
GeneralNicely (and quickly) done PinmemberEd.Poore31-Jul-06 8:18 
GeneralRe: Nicely (and quickly) done PinmemberAshley van Gerven31-Jul-06 23:32 
GeneralNicely Done PinmemberMortman31-Jul-06 6:25 
GeneralRe: Nicely Done PinmemberAshley van Gerven31-Jul-06 23:26 
GeneralMultiple assemblies and cross referencing? [modified] PinprotectorMarc Clifton31-Jul-06 4:18 
GeneralRe: Multiple assemblies and cross referencing? PinmemberAshley van Gerven31-Jul-06 5:25 
GeneralRe: Multiple assemblies and cross referencing? PinmemberEric Woodruff31-Jul-06 7:05 
GeneralRe: Multiple assemblies and cross referencing? PinmemberAshley van Gerven2-Aug-06 12:07 
GeneralRe: Multiple assemblies and cross referencing? PinmemberAshley van Gerven2-Aug-06 12:11 
GeneralRe: Multiple assemblies and cross referencing? [modified] PinprotectorMarc Clifton2-Aug-06 14:27 

General General    News News    Suggestion Suggestion    Question Question    Bug Bug    Answer Answer    Joke Joke    Rant Rant    Admin Admin   

Use Ctrl+Left/Right to switch messages, Ctrl+Up/Down to switch threads, Ctrl+Shift+Left/Right to switch pages.

| Advertise | Privacy | Mobile
Web04 | 2.8.140916.1 | Last Updated 5 Aug 2006
Article Copyright 2006 by Ashley van Gerven
Everything else Copyright © CodeProject, 1999-2014
Terms of Service
Layout: fixed | fluid