取代Sandcastle的新文件產生器DocFx

2016-01-02

3422
0
DocFx

DocFx

DocFx是微軟新推出的文件生成工具，並且也是一個OpenSource的專案(Github)，可以將文件產生網站形式，目前支援C#和VB。與Sandcastle不同的是，可以由nuget下載安裝，並且設定也由xml轉變為json。DocFx還有許多不錯的功能

支援DNX
Markdown
Custom Templates(說明)

接著來看如使用DocFx快速地產出文件吧。

首先，請先使用nuget安裝DocFx的套件，在這裡有一個需要注意的地方，我們需要下載的套件名稱應該是docfx.msbuiled。 nuget docfx.msbuild

為甚麼是docfx.msbuild而不是docfx呢，因為如果是安裝docfx會一直出現.net Framdwork不相容

docfx目前猜測應該是給DNX使用，所以要安裝有特別註明msbuild套件。

安裝好之後可以看到多了一些相關的檔案docfx.json與toc.yml

點開docfx.json，可以看到資料來源和編譯的設定都在這邊，但是，基本上是不需要做任何變更。

{
  "metadata": [
    {
      "src": [
        {
          "files": [ "**/*.csproj" ],
          "exclude": [ "**/bin/**", "**/obj/**" ]
        }
      ],
      "dest": "obj/api"
    }
  ],
  "build": {
    "content": [
      {
        "files": [ "**/*.yml" ],
        "cwd": "obj/"
      },
      {
        "files": [ "**.md", "toc.yml" ]
      }
    ],
    "resource": [
      {
        "files": [ "**/images/**" ]
      }
    ],
    "externalReference": [
    ],
    "globalMetadata": {
    },
    "template": [
      "default"
    ],
    "dest" : "_site"
  }
}

不過，在測試的過程中，筆者遇到一個滿奇怪的環境問題，當專案使用.net Framework 4.5.1時，一直遇到一個奇怪的錯誤