DocFX を用いた C# プロジェクトのドキュメント生成
概要
この記事では、（主に）.NET 系プログラムのドキュメント生成ツール DocFX のコマンドラインでの使い方について書きます。
背景
↑のプロジェクトで、OSS として公開するならドキュメントはいるよね。XML コメントは書いたし、何かいいものはないのかな？と探して DocFX にたどり着き使って、いい……！となったのでこの記事を書くことにしました。まだ日本語の情報は少ないし、いまいちな記事もあるので。なお、このプロジェクトは以下の記事で宣伝しています。
Unity のプロジェクトに NuGet のパッケージをインポートするエディタ拡張を作ったよ
準備
まずは DocFX を落とします。Chocolatey や NuGet にもあるそうですが、私は直接落としました。(GitHub のリリース)
それと、ドキュメント化したいプロジェクトを用意します。（もちろん XML コメントがつけられてるというのが必須です。）
DocFX のプロジェクト作成
以下のコマンドで作業フォルダを作成します。
docfx init -q -o folderName
プロジェクトの設定
プロジェクトの設定さえちゃんとするだけでしっかり動いてくれます。さすがドキュメントのプロジェクトだけあってドキュメントがしっかりしていますが、英語はつらいという方のために基本的なことは書いておきます。ここになかったら公式を見てください。
docfx.json の設定
作業フォルダに docfx.json が生成されていると思います。そちらがこのプロジェクトの設定ファイルです。では順番に見ていきます。
まず、metadata と build の二つに分かれます。ソースからメタデータを生成するフェーズとウェブサイトをビルドフェーズに分けられるためです。（基本一括でやってる。）
metadata の設定
| キー | 説明 |
|---|---|
| src | どのファイルを対象にするか。指定方法はファイルの指定にて。 |
| dest | どのフォルダにメタデータを保存するか。 |
| filter | メタデータのフィルター設定が書かれたファイルへのパス。Unity で使う場合はこれを使わないと大変なことになる。これはフィルターの設定で説明。 |
| shouldSkipMarkup | これを true にすると、XML コメントがマークダウンで表示しなくする。（よくわからない） |
| disableGitFeatures | これを false にすると、Git に適した風になる。（よくわからない） |
| disableDefaultFilter | これを false にすると、デフォルトのフィルタが無効化される。 |
| properties | C# コンパイラにわたすプロパティ（配列）。渡したい # define があるときは DefineConstants というキーを使えばよい。 |
build の設定
| キー | 説明 |
|---|---|
| content | どのファイルをページにするか。yml・md ファイルが指定可能。指定方法はファイルの指定にて。 |
| resource | 画像等のファイルを指定。指定方法はファイルの指定にて。 |
| overwrite | 上書きする yml ファイルを指定。（よくわからない） |
| dest | ウェブサイトの出力フォルダ。 |
| template | ウェブサイトのテンプレート。 |
| disableGitFeatures | これを false にすると、Git に適した風になる。（よくわからない） |
| globalMetadata | ウェブページ全体のメタデータを設定。メタデータの設定で説明。 |
| globalMetadataFiles | ウェブページ全体のメタデータが書いてあるファイルを指定。ファイルの指定はこちら。メタデータの設定はこちら。 |
| sitemap | サイトマップのオプションを指定。サイトマップの設定はこちら。 |
ファイルの指定
以下のようなルールを作ることでファイルを指定する。ここで出てくる Glob パターンについては公式を参照してください。
| キー | 説明 |
|---|---|
| files | 目的のファイルの Glob パターン。 |
| exclude | 除外するファイルの Glob パターン。 |
| src | 参照するディレクトリ。 |
メタデータの設定
以下のようなメタデータを設定できるみたい。あまり書いてなかったのでよくわからない。たぶん Web の方やってる人が詳しいと思う。
| キー | 説明 |
|---|---|
| _appTitle | ウェブサイトのタイトル。 |
| _appFooter | ここで指定した文章がフッターとして表示される。 |
| _enableSearch | ページ内検索できるようにする。私の場合はサイトマップの設定をしないとうまく動かなかった。 |
| _enableNewTab | これが true だと、外部のリンクを開くとき、新しいタブで開くようになる。 |
サイトマップの設定
サイトマップに関する設定。
| キー | 説明 |
|---|---|
| baseUrl | このウェブページのベース URL |
| changefreq | ページ全体の更新頻度。たぶんウェブのキャッシュのやつ。 |
| fileOptions | ファイルごとのオプション。 |
フィルターの設定
メタデータのフィルターに関しては、yml で書きます。デフォルトでは、グローバルな名前空間にあるものは無視されるので、必要であれば含める必要があります。また、継承されたメソッドを全て表示するので、それを非表示にするには、除外する必要があります。Unity であれば以下のようにすればいい感じになるかと思います。
apiRules:
- include:
uidRegex: ^Global
type: Namespace
- exclude:
uidRegex: ^System\.Object
type: Type
- exclude:
uidRegex: ^UnityEngine\.Object
type: Type
- exclude:
uidRegex: ^UnityEngine\.Component
type: Type
- exclude:
uidRegex: ^UnityEngine\.Behaviour
type: Type
- exclude:
uidRegex: ^UnityEngine\.MonoBehaviour
type: Type
- exclude:
uidRegex: ^UnityEditor\.AssetPostprocessor
type: Type
- exclude:
uidRegex: ^UnityEditor\.EditorWindow
type: Type
- exclude:
uidRegex: ^UnityEngine\.ScriptableObject
type: Type
ページの作成
スクリプト以外のドキュメントも作れます。スクリプトのドキュメントだけだとちょっとさみしい。なので、ページを作る方法も少し書きます。
ページの構造を作る
docfx.json の build の content で追加したファイルには必ず toc.yml または toc.md が必要で、このファイルがページの構造を作ります。
プロジェクトの作業フォルダ直下に置いた toc.yml・toc.md では、ヘッダを設定できます。とりあえず例として私のプロジェクトのものを書いておきます。
- name: Documentation
href: documentation/
- name: ドキュメント
href: documentation_jp/
- name: Api Documentation
href: api/
homepage: api/index.md
上の href で指定したフォルダの中にある toc.yml・toc.md はページの左側のコラムとして表示されます。公式ページにあった例を置いておきます。
- name: Topic1
href: Topic1.md
- name: Topic2
href: Topic2.md
items:
- name: Topic2_1
href: Topic2_1.md
ページを作る
マークダウンでページを作ります。どうやら GitHub のマークダウンは全て使えるみたいです。
サイトを見る
以下のコマンドでサイトを localhost:8080 にサーブできます。--serve オプションをつけなければ、サイトを出力のみします。
docfx path/to/your/docfx.json --serve
あとがき
いい感じにドキュメントを作成してくれてすごくいい。しかも早い。
私はなんちゃって多言語対応してるけど、DocFX のバージョン 3 から多言語対応を組み込むらしい。楽しみ。
Discussion