[Visual Studio 2008]C#のソースファイルからヘルプを作成するツールSandcastle
2010年 04月 29日
なおこのツール、ヘルプファイルをコンパイルするためにヘルプコンパイラ(HTML Help Workshop)を必要とする上、コマンドラインツールであるため、GUIを提供するSandcastle Help File Builderを導入するのが賢明と思われる。
世に先人たちのドキュメントが多数あるのだが、最新バージョンのモジュールを導入すると微妙に動きが異なっているので、私の調査した結果をここに記す。
なおこのセットアップの前に、Visual Studioのソースファイルに必要なドキュメントコメントを入れ、プロジェクトのプロパティでxmlファイル名を指定してビルドし、xmlファイルを出力しなければならないのだが、その説明は世の中に良いページがたくさんあるので省略する。
Visual C# .NETでAPIリファレンスを作る(後編)
動作環境
Windows7(x64)
Visual C# 2008 Express Edition SP1
Sandcastle 2.4.10520
HTML Help Workshop and Documentation 1.32
Sandcastle Help File Builder 1.8.0.3
1.Sandcastle.msiをダウンロードして実行し、Sandcastleを入れる。
2.htmlhelp.exeをダウンロードして実行し、HTML Help Workshopを入れる。
もっと新しいバージョンがすでにコンピューターにあるとかいわれるかもしれないが、気にしない。「C:\Program Files (x86)\HTML Help Workshop」というパスにヘルプコンパイラが存在することが重要である。
3.SandcastleBuilderSetup.msiをダウンロードして実行し、Sandcastle Help File Builderを入れる。
4.Sandcastle 日本語化 Revised(やまださんのサイト「いや、まだだから」内)の文章の真ん中らへん、「興味ある方はこちらから。」についているリンクから「Sandcastle_Localize.zip」をダウンロードして、内容をSandcastleインストールフォルダーに展開する。既存のファイルを上書き。(自己責任で。失敗したらフォルダを消してSandcastleを再インストールしてやり直し。)
5.スタートメニューの[Sandcastle Help File Builder]-[Sandcastle Help File Builder GUI]を選択してSandcastle Help File Builder起動。
6.ツールバーの一番左のボタンをクリックするか、メニューの[File]-[New Project]を選択。
7.ファイル保存ダイアログが表示される。ヘルプを作るプロジェクトとの関連がわかる名前をつけて、保存ボタン押下。
8.画面左側に[Project Properties]、画面右側に[Project Explorer]が表示される。
9.プロジェクトエクスプローラ内、[Document Sources]の上で右クリックし、メニューの[Add Documentation Source...]を選択。
10.Visual Studioでビルドしたexeを選択。
11.[Document Sources]の下に、exeとxmlが追加される。
12.プロジェクトのプロパティで以下の項目を設定。
[Comments]セクション
NamespaceSummaries:各名前空間の説明
[Help File]セクション
HtmlHelpName:できあがるヘルプファイル名。例えば、exeと同じ名前にする。
Language:日本語 (日本)
[Visibility]セクション
DocumentInheritedFrameworkMembers:false
13.上記[Comments]セクションのNamespaceSummaries項目で[...]ボタンをクリックすると、Namespace Summariesダイアログが立ち上がる。中段左の名前空間を選択し、下段のテキストボックスに説明を入れていく。「xxx.yyy名前空間には、~するためのクラスが含まれています。」という文章から始まるとMS公式ヘルプっぽい。
14.メニューの[Documentation]-[Build Project]からビルド。時間がかかる。
処理内容は[Build Output]タブに表示される。
15.手順7で作成したshfbprojファイルの階層に「Help」フォルダが作成され、その下に[HtmlHelpName]で指定した名前のchmファイルが作成される。
できあがるchmファイルはこんな感じ。