Sunday, July 30, 2006

Batch file for Microsoft SandCastle CTP .NET documentation compiler

NB: I've since updated the BAT script - available here.

OK the SandCastle CTP is out, but it doesn't have a UI or command line interface. The 11-step instructions at http://blogs.msdn.com/sandcastle/archive/2006/07/29/682398.aspx would be quite a mission to repeat manually each time you need to update your CHM.

I'm probably not the only one to compile a batch file with all the commands. However it certainly wasn't as simple as expected. So I'm sure this batch script will save a lot of time and headaches until the next release of SC.

Steps (or skip to below to download ZIP file):
1) create C:\test_sc\working & C:\test_sc\output
2) Copy C:\Program Files\Sandcastle\Presentation\Configuration\sandcastle.config to C:\test_sc\working and edit this file. Replace "..\..\" with "C:\Program Files\Sandcastle\", "..\cpref_reflection" with "C:\Program Files\Sandcastle\Examples\cpref_reflection", "Output\html" with "..\output\html.
3) Save this batch script and modify lines 2 & 3 to point to your assembly & XML file:

cd "C:\test_sc\working"
copy "C:\test_sc\assembly here\ScrollingGrid.xml" "C:\test_sc\working\comments.xml"
MRefBuilder "C:\test_sc\assembly here\ScrollingGrid.dll" /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
cd "C:\test_sc\output"
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
cd "C:\test_sc\working"
BuildAssembler /config:sandcastle.config manifest.xml
XslTransform "C:\Program Files\Sandcastle\ProductionTransforms\ReflectionToChmContents.xsl" reflection.xml /arg:html="C:\test_sc\output\html" /out:"C:\test_sc\output\Test.hhc"
copy "C:\Program Files\Sandcastle\Presentation\Chm\test.hhp" "C:\test_sc\output\help_proj.hhp"
"C:\Program Files\HTML Help Workshop\hhc.exe" "C:\test_sc\output\help_proj.hhp"
Or you can extract this zip file to "C:\test_sc":

http://www.ixnay2infinity.com/ScrollingGrid/SandCastle_BAT_compile.zip, then modify lines 2 & 3 to point to your assembly & XML file, and run it.

It will output various files to "output" and "working" directory, and finally you should have "Test.chm" in the "output" directory. The default page for the CHM is blank.. just click a node on the left.

NB: two assumptions in this script:
1) you installed sandcastle to default path
2) html help install path is: C:\Program Files\HTML Help Workshop

Hope this is useful.


Post a Comment

<< Home