DocFX - .NET向けAPIドキュメントを生成するツール

Created at: 2016-05-25

誰も触れていなくて紹介しようと思いつつすっかり忘れていたのですがMarkdownGenerator - C#におけるAPI Reference生成のためのドキュメントツールを見て思い出したのでご紹介です。

DocFXとは

DocFXはTools for building and publishing API documentation for .NET projectsとGitHubのリポジトリの説明がある通り、
主に.NETプロジェクト向けのAPIドキュメント生成ツールで、GitHubの.NET Foundation Organizationの下でMicrosoftが開発しています。

昔であればSandCastleなどがありましたが、モダンなツールらしくメタデータやMarkdownなどからHTMLのサイトを生成します。

DocFXのサンプル

試しに、MraaSharpからMraaSharpのドキュメントを生成してみました。
設定やページは若干適当ですが雰囲気は感じていただけると思います。

DocFXができること

DocFXができることには以下のようなものがあります。

.NETのC#/Visual Basicのプロジェクトとソースコードを読み込んでAPIのドキュメントを生成(XMLDoc)
- JavaScriptなどにも対応
- GitHubへのリンクを自動生成
ライブラリの使い方などのページを作る
- Markdownでページを書ける
静的なHTMLを出力
スタンドアローンのサーバーでプレビュー
プラグイン, テンプレートのカスタマイズ

JekyllやHugoなどの静的サイトジェネレーターに近いですが、
そこまで自由なサイトではなく、ドキュメント生成に重きを置いている印象です。

プレビュー中に変更できなかったり、GitHub上のソースコードへ飛べるなどが最初から準備されているのはその辺の考えがあるのではないでしょうか。

DocFXを使って空のサイトを作る

何はともあれDocFXは使ってみるのが一番です。

利用方法はGetting Started with DocFXを見るとコマンドライン、NuGet、ソースからビルド、Visual Studio…といったいろいろな手段があるのですが、
てっとり早く試すのであればコマンドラインがおすすめです。

まずはDocFXのサイトからビルド済みの最新版をダウンロードします。ダウンロード後にアーカイブを展開すると docfx.exe が含まれているのが確認できると思います。

次にコマンドプロンプトを開いて下記のコマンドを実行してプロジェクトを作成します。

docfx init -q -o SampleDoc

Created folder C:\Users\Tomoyo\Downloads\docfx\SampleDoc\src
(略)
Created File C:\Users\Tomoyo\Downloads\docfx\SampleDoc\api\.gitignore
Created config file C:\Users\Tomoyo\Downloads\docfx\SampleDoc\docfx.json
Successfully generated default docfx project to C:\Users\Tomoyo\Downloads\docfx\SampleDoc
Please run:
        docfx "C:\Users\Tomoyo\Downloads\docfx\SampleDoc\docfx.json" --serve
To generate a default docfx website.
Info: Completed executing in 221.5922 milliseconds.

SampleDoc フォルダが作成されてプロジェクトの初期ファイルも生成されます。
-q オプションを外すと設定項目を一つひとつ入力できます。

サイトをビルドする

プロジェクトを作成したらサイトのHTMLを生成してみます。生成するにはSampleDoc フォルダに移動して次のコマンドを実行してください。

..\docfx build

実行すると _site フォルダにHTMLファイルが生成されます。インターネットに公開する場合にはこの _site 以下を何らかの方法でデプロイするとよいでしょう。

サイトを立ち上げてブラウザで表示してみる

ファイルが生成できたら確認のためにプレビューサーバーを起動してみましょう。

..\docfx --serve

Info: Config file docfx.json found, start generating metadata...
Info: No files are found with glob pattern src/**.csproj, excluding **/obj/**,**/bin/**,_site/**, under directory "C:\Users\Tomoyo\Downloads\docfx\SampleDoc"
(略)
Info: [Apply Theme]Theme is applied.
Serving "C:\Users\Tomoyo\Downloads\docfx\SampleDoc\_site" on http://localhost:8080

これで http://localhost:8080/ でサイトが立ち上がります。
ちなみにデフォルトのポート 8080 を利用中の場合には -p オプションを付けて実行することでポートを指定するとよいでしょう。

..\docfx -p 37564 --serve
(略)
Serving "C:\Users\Tomoyo\Downloads\docfx\SampleDoc\_site" on http://localhost:37564

サイトの停止はCtrl+Cです。なお実際はこのコマンドは build も兼ねています。

C#のプロジェクトからソースコードを生成してみる

さて、次はC#のプロジェクトからAPIドキュメントを生成してみます。ドキュメントを生成したいプロジェクトの一式を何か用意しておいてください。

本当はC#のプロジェクトとDocFXのプロジェクトは近い場所に置いておく方がいいと思うのですが、今回は全然違う場所にあるものを指定します。簡単ですので。

docfx.json が設定ファイルとなっているので、このファイルを開いてmetadata の src の場所に “cwd” としてC#のプロジェクトのフォルダパスを指定します(ここでは “C:\Users\Tomoyo\Documents\Work\GitWork\MraaSharp” を指定しています)。

{
  "metadata": [
    {
      "src": [
        {
          "cwd": "C:\\Users\\Tomoyo\\Documents\\Work\\GitWork\\MraaSharp",
          "files": [
            "src/**.csproj"
          ],

そして再度 docfx コマンドでプレビューサーバーを立ち上げると、自動的にC#のコードを解析してXMLドキュメントコメントを読み込み、HTMLを生成します(正確には一旦メタデータファイルを作る)。

プレビューサーバーが立ち上がったのちサイトにアクセスするとナビゲーションに”Api Documentation”が増え、APIのドキュメントにアクセスできます。

Markdownのページを追加してみる

ところでAPIからの生成以外に普通のWebページを追加することもできますので追加してみましょう。ページはMarkdownなどで書けるようになっています。

ページを追加するにはページの内容を書いたMarkdownファイルを作成し、各フォルダ階層に存在する目次ファイルである toc.yml に追記します。

まずはデフォルトで作られる articles フォルダに hello.md ファイルを作成してみましょう。

# Hello!
コンニチハ!

Markdownファイルを作ったら次は toc.yml に追記です。初期状態では intro.md があるのでその後ろに同じようにnameとhrefのセットを足します。

- name: Introduction
  href: intro.md
- name: Hello!
  href: hello.md

そしてまたdotfxコマンドでプレビューサーバーを起動して生成します。生成すると /articles/ 以下に追加したページが並んで表示できるのを確認できるはずです。

終わりに

というわけでDocFXを使うことで簡単に綺麗なドキュメントサイトを生成できるようになります。GitHubにライブラリを公開したけどAPIドキュメントどうしよう…というときにGitHub Pagesとセットで使ったりできます。

まだ少ししか触っていませんが結構細かくカスタマイズできるようになっているので色々調べてみたいところです。

Misuzilla.org

ぷろじぇくと、みすじら。