📄

DocFX を用いた C# プロジェクトのドキュメント生成

2021/02/26に公開

概要

この記事では、(主に).NET 系プログラムのドキュメント生成ツール DocFX のコマンドラインでの使い方について書きます。

背景

https://github.com/kumaS-nu/NuGet-importer-for-Unity
↑のプロジェクトで、OSS として公開するならドキュメントはいるよね。XML コメントは書いたし、何かいいものはないのかな?と探して DocFX にたどり着き使って、いい……!となったのでこの記事を書くことにしました。まだ日本語の情報は少ないし、いまいちな記事もあるので。なお、このプロジェクトは以下の記事で宣伝しています。
Unity のプロジェクトに NuGet のパッケージをインポートするエディタ拡張を作ったよ

準備

まずは DocFX を落とします。Chocolatey や NuGet にもあるそうですが、私は直接落としました。(GitHub のリリース)
 それと、ドキュメント化したいプロジェクトを用意します。(もちろん XML コメントがつけられてるというのが必須です。)

DocFX のプロジェクト作成

以下のコマンドで作業フォルダを作成します。

docfx init -q -o folderName

プロジェクトの設定

プロジェクトの設定さえちゃんとするだけでしっかり動いてくれます。さすがドキュメントのプロジェクトだけあってドキュメントがしっかりしていますが、英語はつらいという方のために基本的なことは書いておきます。ここになかったら公式を見てください。

docfx.json の設定

作業フォルダに docfx.json が生成されていると思います。そちらがこのプロジェクトの設定ファイルです。では順番に見ていきます。
 まず、metadatabuild の二つに分かれます。ソースからメタデータを生成するフェーズとウェブサイトをビルドフェーズに分けられるためです。(基本一括でやってる。)

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.jsonbuildcontent で追加したファイルには必ず toc.yml または toc.md が必要で、このファイルがページの構造を作ります。
 プロジェクトの作業フォルダ直下に置いた toc.ymltoc.md では、ヘッダを設定できます。とりあえず例として私のプロジェクトのものを書いておきます。

toc.yml
- name: Documentation
  href: documentation/
- name: ドキュメント
  href: documentation_jp/
- name: Api Documentation
  href: api/
  homepage: api/index.md

上の href で指定したフォルダの中にある toc.ymltoc.md はページの左側のコラムとして表示されます。公式ページにあった例を置いておきます。

toc.yml
- 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