DocFXを使ってC#のソースコードからAPIのドキュメントを作成

# DocFXとは
C#(というか.NET)のソースコードのコメントから、
[こんな感じ](http://dotnet.github.io/docfx/api/Microsoft.DocAsCode.html)のドキュメントが作成できる。
ただ、スタンドアローンで使うには微妙。

# 環境
Windows7 Professional

# インストール

1. [github](https://github.com/dotnet/docfx/releases)からビルド済みバイナリを取得して展開。
1. [Microsoft Build Tools 2015](https://www.microsoft.com/en-us/download/details.aspx?id=48159) をダウンロードしてインストール。
1. [Node.js](https://nodejs.org/en/)をダウンロードしてインストール。

# 使ってみる

## 初期化
ビルド済みバイナリを展開すると、「docfx.exe」があるので、

```
docfx.exe init -q -o DocFXSample
```

と実行すると、「DocFXSample」ディレクトリが作成される。

![bandicam 2017-02-07 15-57-31-397.png](https://qiita-image-store.s3.amazonaws.com/0/119600/8c169636-2140-0cb9-1b09-61f113e584e6.png)

## C#のプロジェクトとソースファイルを用意
ここではプロジェクト名を**DocFXSample**としたので、
csprojのファイル名は**DocFXSample.csproj**となる。
コメントもつけておく。

```csharp:Program.cs
using System;

namespace DocFXSample
{
    /// <summary>
    /// 基底クラス。
    /// </summary>
    public class BaseClass
    {
        /// <summary>
        /// 基底クラスのメンバ。
        /// </summary>
        public int sum;

        /// <summary>
        /// 基底クラスの仮想メソッド。
        /// sumを+1して返す。
        /// </summary>
        /// <returns>sumの値</returns>
        public virtual int func()
        {
            sum++;
            return sum;
        }
    }

    /// <summary>
    /// 継承クラス。
    /// </summary>
    public class DerivedClass : BaseClass
    {
        /// <summary>
        /// 仮想メソッド。
        /// 基底クラスと異なりsumを+2して返す。
        /// </summary>
        /// <returns>sumの値(derived)</returns>
        public override int func()
        {
            sum++;
            sum++;
            return sum;
        }
    }

    /// <summary>
    /// enumのテスト。
    /// </summary>
    public enum EnumTest
    {
        /// <summary>
        /// 要素1。
        /// </summary>
        Elem1,
        /// <summary>
        /// 要素2。
        /// </summary>
        Elem2,
        /// <summary>
        /// 要素3。
        /// </summary>
        Elem3,
    }
    /// <summary>
    /// enumの拡張メソッドテスト。
    /// </summary>
    public static class EnumTestExt
    {
        /// <summary>
        /// EnumTest.Nameの拡張メソッド。
        /// </summary>
        /// <param name="value">EnumTest。</param>
        /// <returns>EnumTestの値に応じた文字列。</returns>
        public static string Name(this EnumTest value)
        {
            switch (value)
            {
                case EnumTest.Elem1: return "要素1。";
                case EnumTest.Elem2: return "要素2。";
                case EnumTest.Elem3: return "要素3。";
            }
            return "不明。";
        }
    }

    /// <summary>
    /// 実行クラス。
    /// </summary>
    public class Program
    {
        /// <summary>
        /// エントリーポイント
        /// </summary>
        /// <param name="args">引数</param>
        static void Main(string[] args)
        {
            BaseClass b = new BaseClass();
            DerivedClass d = new DerivedClass();
            EnumTest e = EnumTest.Elem1;

            Console.WriteLine("開始。");
            Console.WriteLine("BaseClass     = {0}", b.func());
            Console.WriteLine("DerivedClass  = {0}", d.func());
            Console.WriteLine("EnumTest.Name = {0}", e.Name());
            Console.WriteLine("終了。");
        }
    }
}
```

## 作成したC#プロジェクトとソースファイルを docfx/DocFXSample/src へコピーする。
以下のような感じ。

```
C:\work\docfx\DocFXSample
│  .gitignore
│  docfx.json
│  index.md
│  toc.yml
│
├─api
│      .gitignore
│      index.md
│      toc.yml
│
├─apidoc
├─articles
│      intro.md
│      toc.yml
│
├─images
└─src
        DocFXSample.csproj ← 追加
        Program.cs         ← 追加
```

## metadata/build コマンドを実行。

C#のソースから、**.yml のファイルを作成。

```
..\docfx.exe metadata
```
![bandicam 2017-02-07 16-47-47-817.png](https://qiita-image-store.s3.amazonaws.com/0/119600/02b496f7-0f1d-ef32-00f2-92764f4afa11.png)

_site のデータを作成。

```
..\docfx.exe build
```
![bandicam 2017-02-07 16-48-57-204.png](https://qiita-image-store.s3.amazonaws.com/0/119600/fae19e5b-48b9-f420-4151-e2732b636614.png)

成功すると、docfx/DocFXSample/_site/api/DocFXSample.html が作成される。
ローカルで見る場合はこれで終了。

### 成果物
![bandicam 2017-02-07 16-52-40-742.png](https://qiita-image-store.s3.amazonaws.com/0/119600/f4f50296-0b19-5e73-4ca1-56f00d4b685b.png)

## サーバー起動

```
..\docfx.exe --serve
```

とすると、http://localhost:8080 にwebサーバーが立ち上がり、
作成したドキュメントを閲覧できる。
こちらの方がリッチなコンテンツになる。

### 成果物
![bandicam 2017-02-07 16-54-31-343.png](https://qiita-image-store.s3.amazonaws.com/0/119600/c9fa428a-db94-b930-3797-1f5275a81bbe.png)


# 参考
[DocFX - .NET向けAPIドキュメントを生成するツール](http://www.misuzilla.org/Blog/2016/05/25/Docfx)