Sandcastleでドキュメントを生成

Sandcastle(のCTP版ダウンロードページ)

MSより提供されているドキュメント生成ツール。JavaDocとか、Doxygenとか、そういう感じの。Visual StudioはソースコードにXML形式でコメントを書いておくと、それを自動で読み取ってひとつのXMLファイルにまとめてくれる機能がありますが、そのファイルを解析してもう少し読みやすいフォーマットにしてくれるツールです。たぶん。

現在まだGUIが用意されておらず、またドキュメントの生成手順が非常にめんどくさいのでSandcastle script & configuration utility - Kazzzの日記で紹介されていたSandcastle CHM-compile BAT script and configuration utilityを使って作業を自動化するバッチファイルを生成して使ってみました。

しかし、自分がインストールしたSandcastleではフォルダ構成や一部のEXE(XslTransform)の使用方法が変わっているのか、そのままでは使用できませんでした。

変更点はSandcastleのブログにまとめられていますが、とりあえず上記ツールで自動生成したバッチファイルで修正する点だけを列挙してみます。

XslTransformで.xslファイルのパスを指定するところに/xslオプションをつけないといけない
"art"フォルダの名前が"icons"に変わっている
C:/*/Presentation/ の下に vs2005 フォルダが追加され、artやscriptフォルダはその下に移動されている

ついでに生成したSandcastle.configファイルもフォルダが合わないので手を加える必要がありました。C:/*/Presentation/Transforms/の間にvs2005を挟むだけ。

大体以下のような形になりました。

if not exist output mkdir output
cd output
MRefBuilder "C:\home\develop\hoge\bin\Debug\foobar.dll" /out:reflection.org
if not exist comments mkdir comments
del comments\*.xml
copy "C:\home\develop\hoge\bin\Debug\foobar.xml" comments
XslTransform /xsl:"C:\Program Files\Sandcastle\ProductionTransforms\AddOverloads.xsl","C:\Program Files\Sandcastle\ProductionTransforms\AddGuidFileNames.xsl" reflection.org /out:reflection.xml
XslTransform /xsl:"C:\Program Files\Sandcastle\ProductionTransforms\ReflectionToManifest.xsl" reflection.xml /out:manifest.xml
if not exist html mkdir html
if not exist icons mkdir icons
if not exist scripts mkdir scripts
if not exist styles mkdir styles
copy "C:\Program Files\Sandcastle\Presentation\vs2005\icons\*" icons
copy "C:\Program Files\Sandcastle\Presentation\vs2005\scripts\*" scripts
copy "C:\Program Files\Sandcastle\Presentation\vs2005\styles\*" styles
BuildAssembler /config:../sandcastle.config manifest.xml
XslTransform /xsl:"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\vs2005\Chm\test.hhp" help_proj.hhp
"C:\Program Files\HTML Help Workshop\hhc.exe" "%CD%\help_proj.hhp"
@copy "Test.chm" "C:\home\develop\hoge\bin\Debug\foobar.chm"
@cd ..
REM @rd /s /q output
@pause

修正したバッチファイルを実行したら見事HTMLヘルプが生成されました。MSDN Libraryライクでかっこいいです。

しかしこれを毎回手動で生成するのも大変なので次はビルドツールをインストールしてみようかな。前述のブログにはNAntと組み合わせてビルドと同時にドキュメントを生成する方法も紹介されていたので、その辺参考にしてみよう。