M12i.

学術書・マンガ・アニメ・映画の消費活動とプログラミングについて

VSソリューションにDocFXのプロジェクトを追加する

.NETファミリー(.NET Framework、Mono、.NET Core)向けのドキュメント・ジェネレータの1つにDocFXがあります。このツール自体はVisual Studioやその他IDEからは独立したコマンドライン・ツールですが、Visual Studioソリューションの中でそのバイナリや設定ファイルを管理できると何かと便利そうです。というわけで、やってみました。

1. 下準備

まず今回の作業のためにサンプルのライブラリのソリューションを用意しました。もちろん実際にはここでドキュメント生成の対象とするソリューションをオープンするということになります:

f:id:m12i:20170708203415p:plain

あくまでサンプルなのでほとんど中身のないライブラリです。ダミーのクラス(public指定)とインターフェース(非public指定)だけです:

f:id:m12i:20170708203457p:plain

2. ドキュメント生成用のプロジェクトを追加

ソリューションに新しいプロジェクトを追加します。もっと良い方法があるのかもしれませんが、今回はクラスライブラリのプロジェクト・テンプレートを選択しました:

f:id:m12i:20170708203415p:plain

追加されたプロジェクトには自動でClass1.csなどのファイルが追加されますが、これらは不要なので削除します:

f:id:m12i:20170708203625p:plain

3. ドキュメント生成のための参照を追加

参照マネージャーを起動して(VS2017の場合、ソリューション・エクスプローラー内でドキュメント生成用プロジェクトの[参照]を右クリック→[参照の追加]をクリック)、ドキュメント生成の対象となるプロジェクトを選択します:

f:id:m12i:20170708204400p:plain

NuGetパッケージ・マネージャーを起動して(VS2017の場合、ソリューション・エクスプローラー内でドキュメント生成用プロジェクトの[参照]を右クリック→[NuGetパッケージの管理]をクリック)、"docfx.console"を検索してインストールします。インストールに際して提供者Microsoftのライセンスに同意を求められます:

f:id:m12i:20170708204543p:plain

4. DocFXの設定ファイルを編集しビルド

"docfx.console"のインストールが終わると一連の雛形ファイルがドキュメント生成用プロジェクトに追加されます。このなかの"docfx.json"をオープンして、コードを追加します:

f:id:m12i:20170708204736p:plain

JSONファイルのルート直下のプロパティ("metadata"とか"build"とか)はDocFXのコマンドライン・ツールを実行するときのサブコマンド名として認識されるもののようです。この中の"metadata"のセクションにある"src"プロパティ──"docfx metadata"コマンドで処理対象となるソースコードの定義情報──に, "src": "../(ドキュメント生成対象のプロジェクトのフォルダ名)"という一行を追加します。これでひとまず準備完了。

プロジェクトをビルドします(VS2017の場合、ソリューション・エクスプローラー内でドキュメント生成用プロジェクトを右クリック→[リビルド])。次のキャプチャ画像に示したような出力が行われます。すべて正常終了したことを確認します:

f:id:m12i:20170708205346p:plain

5. 生成されたドキュメントを確認

VS2017のソリューション・エクスプローラーには表示されませんが、プロジェクト・フォルダの直下に"_site"というフォルダがあり、そこに生成されたHTMLドキュメントが出力されています。"index.html"をIE Edgeで表示すると次のようにデフォルトのテンプレートでレンダリングされたドキュメントを閲覧できます:

f:id:m12i:20170708202426j:plain

"API Documentation"をクリックすると、ドキュメント生成対象のライブラリが公開しているメンバーの情報を閲覧できます:

f:id:m12i:20170708202510j:plain

なんとも残念なことにChromeブラウザで表示すると、XMLHttpRequestによるコンテンツのロードがクロス・オリジン・リクエストのエラーのため失敗しており、"toc.yml"で定義されている情報がロードできないために、各種ナビゲーションが無効になっています:

f:id:m12i:20170708202608j:plain

生成されたドキュメントを確認する方法としてはもう1つ、開発PC上でWebサーバを起動してそれ経由で配信されるコンテンツをWebブラウザで閲覧するというものがあります。この方法であれば上述のエラーは起きません:

> cd (プロジェクト・フォルダのパス)
> set PATH=..\packages\docfx.console.(NuGetでインストールしたバージョン)\tools;%PATH%
> docfx --serve