Sandcastle script & configuration utility

Sandcastle Blogを始めとして、以前に紹介したいくつかのサイトでは、SandCastleを使ってVisual Studioが吐いたXMLコメントを新MSDN風のHTMLヘルプ形式(chm)のドキュメントに変換する方法が書かれていたが、その方法で使用されるバッチファイルを自動で出力してくれるユーティリティがCodeProjectに掲載されていた。

Sandcastle CHM-compile BAT script & configuration utility

このツールは.NET C#/WindowsFormsで書かれたもので、対象となるアセンブリとXMLコメントのパスを指定することで、変換用のバッチファイルを出力する簡単なものだ。例えば、"E:\Hoge\Hoge\bin\Debug\Hoge.dll"というアセンブリ、及び対応するXMLコメントファイル"Hoge.XML"を対象とすると、以下のようなバッチファイルが出力された。

if not exist output mkdir output
cd output
MRefBuilder "E:\Hoge\Hoge\bin\Debug\Hoge.dll" /out:reflection.org 
if not exist comments mkdir comments
del comments\*.xml
copy "E:\Hoge\Hoge\bin\Debug\Hoge.XML" comments
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" "E:\Hoge\Hoge\bin\Debug\Hoge.chm"
@cd ..
REM @rd /s /q output
@pause

ちなみに自動出力されるバッチファイルはSandCastleが"C:\Program Files"を基点にインストールされている事を前提にしているので、他のフォルダにSandCastleをインストールしている場合は修正が必要だろう。

早速出力されたバッチファイルをを実行してみたが、何故か上手くいかない。

Error: Unresolved assembly reference: System.Configuration (System.Configuration, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a) required by Hoge

これはバッチファイルの最初に実行されるMRefBuilderから出力されたエラーメッセージなのだが、どうやらSystem.Configurationアセンブリの解決に失敗している模様。いろいろと調べた結果、対象のアセンブリが依存する、いくつかのGACに登録されたアセンブリに関して、手動で解決をしないと上手く動かないようだ。(これはあきらかに不具合だ。CTPだからだろうか。)
幸いMRefBuilderには外部アセンブリを解決するための/depスイッチが用意されているので、これを使って依存アセンブリを解決してやるように、バッチファイルを書き換えてみた。

MRefBuilder "E:\Hoge\Hoge\bin\Debug\Hoge.dll" /out:reflection.org /dep:"C:\windows\Microsoft.NET\Framework\v2.0.50727\System.configuration.dll","C:\windows\Microsoft.NET\Framework\v2.0.50727\System.Deployment.dll"

ビンゴ。これで上手く動くことを確認できた。ちなみに、これは対象としたアセンブリが、"System.configuration.dll"と"System.Deployment.dll"を参照しているためであり、アセンブリによってカット&トライが必要かもしれない。

最後にSandCastleで出力されたドキュメントのスクリーンショットを載せておこう。

体裁としては最新のドキュメントエクスプローラで見るVisual Studio 2005のヘルプ-リファレンスドキュメントに似ている。NDocのように日本語も化けないし、既に違う言語(C# or Visual Basic)の切り替えにも対応している。また、BindingFlagsの属性を利用したメンバ情報(コンストラクタ、メソッド、プロパティ、フィールド、イベント)の表示/非表示の切り替えにも対応しているようだ。

このスクリーンショットでは無いが、カスタム属性も表示される、全てのメンバの型階層でハイパーリンクが張られる、など従来のMSDN形式ドキュメントよりも表現、操作性に優れており、これならNDocの後継足りうるだろう。

追記:

生成したてのCHMドキュメントを開くと、最初のページが以下のように表示されてしまうことに気がついた。

見栄えが悪いので、適当なページか画像に差し替えたいのだが、今のところ方法が解らず。