Monday, July 31, 2006

Sandcastle BAT script configuration utility

UPDATE: Now supports wild cards (i.e. multiple assemblies/xml-comments files).

I've whipped together a little windows app to configure and create the BAT script that I posted yesterday which calls the various steps to get Sandcastle-generated MSDN-style documentation:


NB: The app includes the BAT script - you do not need to download it separately.

1) Unzip all files, and open SandCastleCreateBat.exe.
2) Specify file paths
3) Click Create BAT to output BAT script + sandcastle.config to the same directory as as the CHM path.


For detailed information visit: http://www.codeproject.com/useritems/SandcastleCreateBat.asp

Feedback would be appreciated.

Improved SandCastle BAT script

(Update: I've made a windows app to configure the paths and save the BAT script - click here)

Yesterday I posted my initial BAT script to automate the 11 steps to create a CHM using Microsoft's SandCastle CTP. Well there were a couple of limitations, so here is the updated BAT script: http://www.ixnay2infinity.com/ScrollingGrid/SandCastle-BAT-compile-updated20060731.zip

Contents of readme.txt:

Description: BAT file to create CHM file containing MSND-style class documentation for your assemblies using Microsoft Sandcastle CTP (July 29 2006)
Author: Ashley van Gerven (http://ixnay2infinity.blogspot.com)

1) Extract this zip file to a working directory (ANYWHERE!)
2) Modify line 3 to point to your assembly
3) Modify line 4 to point to your comments XML file
4) Modify line 18 and change "ScrollingGrid.chm" to the your CHM filename. You can also set the full destination path to the resulting CHM file.
5) Run the BAT script, and you should end up with your CHM file in the working directory or where you specified

NB - Requirements:
1) You installed Sandcastle to the default path: C:\Program Files\Sandcastle
2) You installed HTML Help 1.4 SDK to the default path: C:\Program Files\HTML Help Workshop
3) You have .NET framework 2.0 installed

This BAT has several improvements over my initial BAT script of yesterday which had the C:\test_sc path hard-coded and required replacing this string to the current path of the BAT. This is no longer required.

Note 2:
If you don't want the ouput folder (containing all the HTML files, Help project etc) to be deleted after compiling the CHM just prepend "REM" to the second-last "@rd..." line.

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.