Sandcastleを使ってみた

SandCastleを使ってみて、自分なりのまとめ。Html Helpのコンパイラを持っていないのとそもそもWEBページとして作成したかったのでそういう設定の例。

• Sandcastleをインストールする。これはシステム環境変数DXRootを設定するので管理者権限の方が良い。(ユーザ権限でもユーザ環境変数に登録するかもしれないが未確認)
• Sandcastle Help File Builderをインストールする。管理者権限でインストールしたが、この権限が必須かは未確認。
• 生成されるヘルプファイルは何もしないと英語・日本語交じりになる。ローカライズするためには現行のバージョン( SandcastleのMay 2008 Release (Version 2.4.10520) と Sandcastle Help File Builder の Version 1.7.0.0)では以下の方法でうまく入った。このエントリから Sandcastle_Localize.zip をダウンロードする。この中のPresentationフォルダの中身のみSandcastleのPresentationフォルダにコピーする。他のフォルダに入っているファイルについては対応する修正が現行バージョンではなされている。ネタ元として参照されているエントリにも色々書いてあるが全て現行バージョンでは対応する修正がなされているためこれだけで十分。
• Visual C# 2008(私の場合はexpress editionを使用)のツールメニューから``外部ツール'を選択して、以下の設定を登録する。
  • タイトル＝Sandcastle Help File Builder
  • コマンド=C:\Program Files\EWSoftware\Sandcastle Help File Builder\SandcastleBuilderConsole.exe
  • 引数=$(ProjectDir)$(TargetName).shfb
  • ``出力ウィンドウを使用''にチェックを入れておく。
  なお、必要ならば``起動時に引数を入力''のチェックも入れる。
• C#のプロジェクトのプロパティのビルドタブで``XMLドキュメントファイル''にチェックを入れる。XMLファイル名は必ずしも指定しなくて良い。勝手に生成される。またドキュメンテーションコメントを付けていない項目がたくさんある間は警告メッセージが煩いので``警告の表示なし''の横のテキストボックスに1591と書いておく。
• 一度C#のプロジェクトをビルドする。一応bin/releaseにxmlファイルが出来たか確認する。
• Sandcastle Help File Builderを開いて``Project''-``New Project From Visual Studio Project''からソリューションまたはプロジェクトを選択。bin/debugとbin/releaseのどちらにあるxmlファイルを使うか聞かれる。普通はbin/releaseが良いと思うのでそう選択する。
• 多分自動で設定されるけれどFrameworkVersionは自分のプロジェクトに合わせる。HelpFileFormatは``Website''に（他の選択だと対応するHTML Helpのコンパイラが必要)。Languageは``日本語''にすると少しローカライズされる。NamingMethodを``MemberName''にすると生成されるファイルのファイル名が分かり易くなる。PresentationStyleをvs2005にすると現行のMSDNと類似のフォーマットで出力される。ShowMissingNamespacesは``False''にする(あるいは右上にある``Namespaces''で何かしら設定する)。
• 他にHelpTitle, CopyrightHref, CpyrightText, FeedbackEMailAddress, FeedbackEmailLinkTextをそれぞれ設定すれば表示される内容をカスタムできる。
• SdkLinkTypeを``None''に、DocumentInheritedMembersを``False''に、DocumentInheritedFrameworkMembersを``False''に設定するとビルドが劇的に早くなるとの情報があるが実際に劇的に早くなるかは未確認。SdkLinkTypeはSDKの(というか.Net Frameworkの)要素にリンクを張る方法を、インターネットのMSDNにするかローカルのヘルプファイルにするかリンクを張らないかの三択で選択するのだが、MSDNと設定してインターネット上のMSDNにリンクするようにするとめちゃくちゃ便利。例えば<see cref="IEnumerable&lt;T&gt;">と書くと対応するMSDNのページにリンクされる。それから、DocumentInheritedMembersやDocumentInheritedFrameworkMembersはポリモルフィズムによって継承によって作成したクラスは継承元のメンバを持つわけだがそれを一覧に表示するかどうか。System.Objectから継承されるメンバなんかも表示されて煩いのでDocumentInheritedFrameworkMembersは切った方が良いかも。DocumentInheritedMembersはお好みで。
  
• Sandcastle Help File BuilderのプロジェクトをC#のプロジェクトファイルと同じディレクトリに、プロジェクトのプロパティのアプリケーションタブから確認できる``アセンブリ名''と同じ名前で拡張子を.shfbとして保存する。
• Visual C# 2008から念のためもう一度プロジェクトをビルド。XMLドキュメンテーションコメントの不備はエラーでなく警告で表示されるので自分で``エラー一覧''タブを開いて確認する。問題なければ、ツールメニューから``Sandcastle Help File Builder''を選択。すごく時間がかかるけれどしばらく待つと
  Completed
  The help output is located at: ほにゃらら
  Build details can be found in ほにゃらら
  というメッセージが出力ウィンドウに表示されて、プロジェクトのフォルダのHelpフォルダの中にドキュメントが生成される。Index.htmlを開いて内容を確認する。