このページではC#／VB.NETのXMLコードコメントからAPIドキュメント（ヘルプファイル）を生成できる「Sandcastle」と「Sandcastle Help File Builder」について解説します。
SandcastleとSandcastle Help File Builderとは
Sandcastleは、ソースコードに記述したコメントを解析して、ヘルプドキュメントを生成できるツールです。JavaDocの.NET版のようなものです。当初はMicrosoftにて開発された社内ツールでしたが、現在はオープンソースとして公開されています。
Sandcastle Help File Builderは、Sandcastleを簡単に使用するためのサポートGUIツールです。Sandcastleのコマンドラインツールを使うよりも、Sandcastle Help File Builderを利用することが一般的です。
[準備1] Sandcastleのインストール手順
Sandcastleのインストール手順は、ガイド形式のウィザードのインストーラを使用します。依存するファイルを随時インストールしていきます。
まず、CodePlexからSandcastle Help File Builderをダウンロードしてインストールします。SHFBGuidedInstaller_XXXX.zipを解凍後、インストーラ（SandcastleInstaller.exe）をダブルクリックすると、「Sandcastle Guided Instllation」が起動します。
[準備2] 出力するヘルプの種類と形式
ヘルプを出力できる形式は以下の通りです。
- HTML Help 1・・・HTMLを1つのファイルにまとめたヘルプ形式(*.chm)。
- Microsoft Help 2・・・Visual Studio2008やOffice2007等で利用されているヘルプ形式(*.HxS )。MSDNヘルプに組み込む形で使用。
- Microsoft Help Viewer・・・Microsoft Help 3 とも呼ばれVisual Studio2010以降のHelpViewerで見ることができる形式(*.MSHC)。
- Websites・・・ブラウザで見れる形式
これらのヘルプ生成に必要なファイルが無い場合は次のように警告が出ます。必要があればリンクをクリックしてインストールし、不要であれば、そのまま「はい」を押して進みます。
次にSandcastleのインストールを進めます。
[準備3] Sandcastle本体のインストール
Sandcastleサイトで公開されているバージョンよりも、このインストーラから入手できるバージョンのほうが新しいため、「Install Sandcastle」ボタンをクリックします。なお古いバージョンのSandcastleをインストールしている場合は手動でアンインストールしておく必要があります。
「Install Sandcastle」ボタンを押してしばらくすると、自動的にインストーラが立ち上がってきます。インストールするコンポーネントを選択します。とくにデフォルトのままで問題ないでしょう。
インストールが完了するとSandcastleのツール群がインストールされます。コマンドラインツールのため直接操作することはほとんどありません。
[準備4] Visual StudioにMAMLツールをインストール
MAML（Microsoft Assistance Markup Language）とは、WindowsVISTAのAP Help形式(Assistance Platform) を記述するためのマークアップ言語です。
ここでは、Visual StudioにMAML Schema のインテリセンスをインストールするか聞かれます。普通は必要ありませんが、必要があれば「Install Schema」をクリックして、OKを選択します。さらにMAMLスニペットをVSにインストールするか聞かれます。これも必要があれば「Install Snippet」をクリックして、OKを選択します。
[準備5] Sandcastle Help File Builderのインストール
次にメインのGUIツールであるSandcastle Help File Builder（略してSHFB）をインストールします。
「Install SHFB」をクリックするとインストーラが立ち上がってきます。
インストール先を指定して、次へをクリックしていきます。
[準備6] Visual StuidoにSHFBプロジェクトをインストール
Visual StudioでSHFBを利用する場合は、Install Packageボタンをクリックします。Visual Studio2010以上かつExpressエディション以外で使用できます。Visual Studioの有償エディションを持っている場合は利用すると良いでしょう。
これで、インストールは完了となります。続けて設定を行います。
[設定1] コメントを記述するプロジェクトの設定
コードコメントを記述するプロジェクト（C#）を作成します。そしてプロジェクトのプロパティを開き、ビルドタブで「XMLドキュメントファイル」にチェックを入れます。ファイル名はデフォルトで問題ありません。
この設定でビルドするとXMLファイルが生成されます。
なお、XMLコメントを書くときは、GhostDocを利用すると楽に記述することができます。
[設定2] Sandcastle Help File Builderの起動
スタートメニューから「Sandcastle Help File Builder GUI」を起動します。
最初に、FileメニューからNew Projectを選択して、SHFBのプロジェクトファイル(*.shfbproj)を作成します。
次に、プロジェクトエクスプローラのDocumentation Soucesで右クリックをして、Add Documentation Sourceを選択します。
そしてヘルプファイルを生成する対象のDLLを選択します（ここではMvcApp.dllを選択）。
[生成] Sandcastle Help File Builderの実行
ヘルプを生成するには、Documentメニューから「Build Project」を選択します。ウィンドウにログが表示されます。「Build completed successfully」と表示されれば完了です。
Documentationメニューから生成されたファイルを見ることができます。
CHMファイルが生成され、コメントに設定した文言が表示されていることが確認できます。
[応用1] Visual StudioでSandcastle Help File Builderプロジェクトの作成
Visual StudioのIDE内で、Sandcastle Help File Builderを呼び出せるようになりましたので、その方法について紹介します（Sandcastleプロジェクトを作成しておくと、チームメンバーに、Sandcastleのことを意識してもらいやすくなります）。
ソリューションから新規プロジェクトの追加を選択し、Documentaionというテンプレートから、「Sandcastle Help File Builder Project」を選択します。
プロジェクトが作成できたら、ソリューションエクスプローラを開き、Documentation Sourceから、コメントを生成したいプロジェクトのアセンブリを選択します。
SHFBプロジェクトをビルドすれば、ヘルプドキュメントが生成されます。
[応用2] コマンドプロンプトでの実行（ビルドサーバー）
Sandcastleはコマンドプロンプトから呼び出すこともできます。Jenkinsのようなビルドサーバーで定期的にヘルプファイルを生成できます。
SHFBのプロジェクトファイルはMsBuildから呼び出すことができます。コマンドライン構文は次の通りです。
Msbuild.exe /p:ビルド設定 “/property:SHFBROOT=SHFBのインストール場所” “SHFBのプロジェクトファイルのパス”例えば次のようになります（実際は１行）。
C:\Windows\Microsoft.NET\Framework\v4.0.30319\MSBuild.exe /p:Configuration=Debug "/property:SHFBROOT=C:\Program Files (x86)\EWSoftware\Sandcastle Help File Builder" "C:\SandcastleSample\Document.shfbproj"[応用3] 日本語ヘルプファイルの出力
Sandcastleが出力するAPIドキュメントを日本語で読みやすくすることができます。
まずSHFBプロジェクトの設定で、Help file languageを「Japanese（Japan）」に変更します。さらに、PresentationStyleを「VS2010」に変更します。
日本語出力をするためには、日本語にローカライズしたファイルをSandcastleフォルダに配置する必要があります。インストールフォルダにプレゼンテーションスタイルに応じた日本語リソースファイルを配置します。
ここではVS2010スタイルなので、以下のフォルダに配置します。
C:\Program Files (x86)\Sandcastle\Presentation\vs2010\Content\ja-JP
配置するファイルは、このサイトの「sandcastle_vs2010_ja-JP」から入手できますので、必要があればダウンロードしてください（Help.1 CHM用の必要最低限翻訳です）。解凍してからru-RUと同じ構成になるように配置してください。
あとは、ドキュメントをビルドすれば、以下の様な日本語のドキュメントを生成できます。ツリーの部分や「継承階層」「構文」といった説明文言が日本語になっていることを確認できます。
<追記> こちらのサイトにてSandcastleの日本語リソースが公開されていました。
[応用4] 名前空間の説明文言の追加
XMLコメントでは名前空間（namespace）に関する説明を書くことはできません。そのため、Sandcaslte Help File Builderにて名前空間に関する補足を書くことができます。プロジェクトのプロパティの「Summaries」タブにて「Edit Namespace Summaries」をクリックして編集することができます。ウィンドウを閉じてから、ドキュメントを生成すればその説明がAPIファイルに埋め込まれます。
