Sandcastleを最低限使うための最初のメモ
縦割りじゃなくて横割りの開発をする場合には、層ごとに公開するAPIのドキュメントは必須ですよね。
そんな訳で、Silverlight開発というか、C#開発でのAPIドキュメントの作り方を調べます。
どんな方法があるのか？
Javaで開発をしていた頃はチームの方針でJavadocを使っていました。Eclipseからもさっくり作れて簡単でした、きっとMS様のことなのでさらに簡単に作れる方法を提供してくれている事でしょう。ワクワク
とりあえず２つ
見つかりました。
- Sandcastle
- NDoc
こちらのエントリによりますと、ドキュメント作成の方法が後２つぐらいあるのと、NDocがメンテされてない、Sandcastleが定番という事らしいです。なるほど。
そんな訳で
Sandcastleを採用する事にします。
Sandcastleの導入
インストールしたのは以下の二つです。リンクはTopページにしてあるのでDownloadページでダウンロードしてください。
インストールはインストーラが付いているので何も考えなくてOK。
Sandcastle Help File Builder はコマンドラインのSandcastleをGUIで使えるようにしてくれるようです。便利！！
Sandcastleを使ってみる
自分としてはJavadocのブラウザからさくっと見られる感じが好きだったので、普通のHTML形式での出力でやってみます。
0. 準備
ドキュメントを作りたいプロジェクトをVisual Studioで作っておきましょう。今回はVisual Studio 2008 Proでやってますが、Visual Studioからは何もやってないのでバージョンは何でもいいです。
加えて以下が必要です。
- プロジェクトのプロパティの「ビルド」の項目において、リリースのXMLドキュメントを作成するようにチェックを付ける
- 参照設定されているもの全てのローカルコピーを「True」にする。（これはSandcastle側でRefelense設定するのが面倒だから。）
- リリースビルドをして正常終了する事を確認し、出力されたDLLとXMLファイルの場所を確認しておく。
1. 新規プロジェクトを作る
File -> New Projectを選択すると、選択画面が出てくるのでドキュメントファイル作成のルートとなる場所に名前を付けてSandcastleのプロジェクトファイル(.shfbproj)を作ります。
プロジェクト単位で作りたいなら.projファイルがある場所に同名で作る、複数プロジェクトのドキュメントを同時に作るなら、.slnファイルがある場所に同名で作ればいいんじゃないかな。（適当...）
今回はEntityDataModelSampleっていう過去に作ったプロジェクトに対してやっています。よってこんな感じ。
EntityDataModelSample/ + EntityDataModelSample.proj + EntityDataModelSample.shfbproj + Bin/ | + Release/ | + EntityDataModelSample.dll | + EntityDataModelSample.XML + ソースとか..
すると、こんな感じの画面が出てきます。
2. ドキュメント生成対象を設定する。
Project ExplorerからDocumentation Sourceを右クリックしAdd Documentation Source...を選択します。
ファイル選択画面になりますので、準備で生成しておいたdllを選択します。
すると、dllとxmlがProject Explorerに追加されます。
Referenceには何も設定しません、ローカルコピーで全て上記で設定したdllと同じ場所にあるからです。
（というか、正直Referenceの設定に関してはまだよく理解できていないので、とりあえずローカルコピーTrueで成功したからそうしているだけですorz..）
2.5 詳細なプロジェクトのプロパティを設定する前に..
この時点で一度ドキュメントを作ってみます。ただし、HTML Helpのコンパイラが無いと無理だけど。。持ってると仮定して。(C:\Program Files\HTML Help Workshopとかあればたぶん大丈夫。)
リリースモードにして、Documentation -> Build Projectを選択すればOKです。Build Outputタブが現れてゴリゴリと作ってくれます。
reference resolve errorみたいなのが出てたら参照がまずいと思います。ローカルコピーを確認してみてください。
さて、成功したら早速確認してみましょう！まずどこにできているかですが、以下の場所にできています。
EntityDataModelSample/
+ EntityDataModelSample.proj
+ EntityDataModelSample.shfbproj
+ Bin/
| + Release/
| + EntityDataModelSample.dll
| + EntityDataModelSample.XML
+ ソースとか..
+ Help <== ココ！！
+ Documentation.chm
+ LastBuild.logDocumentationというのはデフォルトの名前なので変更可能です。
3 詳細なプロジェクトのプロパティを設定する（少しだけ..）
| プロパティカテゴリ | プロパティ名 | 変更値と理由 |
|---|---|---|
| Build | FrameworkVersion | 3.0 |
| HelpFileFormat | Website (素のHTMLで欲しいので) | |
| Comments | NamespaceSummaries | 名前空間の説明を書きたい |
| ProjectSummary | プロジェクトの説明を書きたい | |
| Help File | Help Title | タイトルを設定したい |
| Language | 日本語 | |
| NamingMethod | MemberName |
とりあえずこれぐらいでしょうか、後はおいおい調べていかないと。。
4 Websiteとして出力する
さて、3の設定で出力をWebsite形式に変えたので、次のビルドでは出力が変わるはずです。さっそくビルドしてみます。
...こんな小さなプロジェクトでも２分近くかかりますね。。
ではフォルダ構成はどうなっているでしょうか。
EntityDataModelSample/
+ EntityDataModelSample.proj
+ EntityDataModelSample.shfbproj
+ Bin/
| + Release/
| + EntityDataModelSample.dll
| + EntityDataModelSample.XML
+ ソースとか..
+ Help
+ Index.html
+ Web.config
+ Index.aspx
+ .....etcWeb.configやaspx拡張子のものができている事から分かるとおり、ASP.NETのデータもできています。これをIISにホストしてもいいのですが、うちのサーバーマシンはあいにくLinuxですし、検索とは必要ないので単純に静的なページを閲覧できるだけでよいわけです。
では、Index.htmlをブラウザで開いてみましょう。APIドキュメントが表示されたでしょうか？
より使いこなすために参考にしたいエントリー
ありがたく参考にさせていただきます。
