Sandcastle使ってみた
.NET系言語でおなじみのXMLドキュメンテーション。を、きれいなHTMLヘルプにしてくれるツール。
CodePlex Archive
こんなツールは誰が作ってるのかと思えばMS先生ですか。ここまで来たらVSに同梱してもいいような気がしますが。
Sandcastle自体はヘルプ生成ツールキットのようなものでCUIでの作業がメインになるようです。
インストール
最低限必要なのはSandcastle本体とHTML Help Workshopだけなので個別にインストールします。
あるいは、ヘルプ生成までGUIで作業できるツール(Sandcastle Help File Builder)にインストールウィザードのようなものが付いているので、これを使うのも手です。
CodePlex Archive
ビルド時に自動生成したい人は（ちょっと古いですが）このあたりを参考にするといいかもしれません。
自作したクラスライブラリのヘルプ（ドキュメント、仕様書）を作成する - .NET Tips (VB.NET,C#...)
作ってみる
Sandcastle Help File Builderを起動し、ソリューションディレクトリにプロジェクトを作成します。デフォルトではこの下にHelpというフォルダが作られ、中間ファイル・出力ファイルは全てそこに作られることになります。
次に右側のProject ExplorerのDocumentation Sourcesを右クリック、Add Documentation Source...で.slnファイルを指定します。ソリューションに含まれるプロジェクトのうち、ツールバーにある構成・プラットフォームに該当するものだけが使われます。Mixed Platformsは選べないので注意。
中央のProject Propertiesでヘルプ生成の設定をします。各項目の概要は以下の通り。
- Build
- 生成自体に関する全般的な設定。フレームワークのバージョンや生成するヘルプ形式など。
- Comments
- ヘルプ生成プロジェクトの概要、名前空間ごとの概要、ヘルプに含める名前空間の設定。
- Help File
- ヘルプ全体の設定。タイトル、連絡先、言語*1、スタイルなどが含まれます。
- HTML Help 1
- .chmに関する設定。お気に入りタブを含めるか、MSDNへのリンクを生成するかなど。
- MS Help 2
- VS2005-2008のヘルプ、.HxSに関する設定。VS2010では使われていませんが・・・
- MS Help Viewer
- VS2010で採用されたヘルプマネージャ用コンテンツに関する設定。
- Paths
- 作業ディレクトリ、ヘルプコンパイラ、出力ディレクトリなどを指定します。
- Show Missing Tags
- ドキュメンテーションの不足している項目にメッセージを表示するかどうかの設定。
- Visibility
- アクセスレベルやフレームワークとの絡み方で非表示にする項目の設定。
- Website
- ウェブサイトとして生成する際の設定。要はHTMLの集合ですね。
設定が出来たらDocumentation→Build Projectで生成します。少し時間がかかるのでのんびり待ちましょう。
"Build copleted successfully"と表示されたら完成です。Documentation→View Help Fileからできあがったヘルプを表示できます。
メモ
- Visibility/DocumentInheritedFrameworkMembersをFlaseにしておかないと、フォームを含むときとかで悲惨なことになる
- 自分で使うだけならVisibility/DocumentInternalsをTrueにしておくと便利
- Show Missing Tagsはコメント付け忘れ防止にTrueのままにしておいて、配布するときだけFalseにする感じだろうか
- VSのヘルプマネージャに統合されるのは結構楽しい。よく使う自作ライブラリがあるなら入れておくと便利だろうなー。
