【Visual Studio 2005】ドキュメントを自動生成する「Sandcastle」

Vistual Studio 2005+vb.netのXMLドキュメントを自動的にMSDNのヘルプ形式に変換してくれるツールの紹介。

3年ぐらい前に調べたときは見つけられなかった。

@IT - 特集:ツールを使ったドキュメント作成技法(前編)

ここのブログを参考に。

必要なツールは

Sandcastle ・・・ コマンドベース(現在:2.4.10520)

Sandcastle Help File Builder ・・・ SandcastleをGUIで操作(現在:1.7.0.0)

両方msi形式をダウンロードしてインストール。Microsoftで作成されたフリーのツールらしい。インストール自体はmsiを実行するだけで終了。

Sandcastle Help File Builderを起動して、addボタンからコンパイル時に生成されるXMLドキュメントのxmlファイルを指定。これを生成するためにはVisual StudioのMy Project→コンパイル→「XMLドキュメントファイルを生成する」にチェックする。デフォルトで入っているはず。

image

ヘルプファイルの生成は
Documentation → Build Project

Project Propert
└Help File 
   └Language

は日本語を選択しとく。

Error: Unresolved assembly reference
と怒られる場合は、依存関係のファイルを指定しないと駄目らしいので

Project Propert
└Build
   └Dependencies

に依存しているdllファイルなどを指定。デフォルトではprivateのメソッドを出力してくれないので、

Project Properties
└Visibility
   ├DocumentAttributes
   └DocumentPrivates

などはTrueの方がいいかも。他はお好みで設定。参考

ビルド自体はちょっと時間がかかるけど、名前空間や命名規則をしっかり管理していると、とても見やすいドキュメントになる。

ステキすぎる。

<2009/05/08 追記>
Sandcastle Help File Builderのバージョンが1.8.0.1 Betaに上がっていたのでインストールし直してみた。

新規にプロジェクトを作成した後にProject Explorerの「Documentation Sources」にVisual Studioのvbprojファイルを追加しただけでヘルプファイルを自動生成してくれた。

依存関係とかうまいこと解決してくれるみたい。