開發中，有一句話叫 最不喜歡的是寫文檔，最不喜歡的是看別人家代碼沒有文檔。那么世界上文檔寫最 la 好 ji 的就是微軟了，那么微軟的api文檔是如何做的？難道請了很多人去寫文檔？

實際上微軟有工具用來生成 api 文檔和教程。

我這里說的微軟文檔是：https://docs.microsoft.com/en-us/dotnet/articles/csharp/index 這個網站，不是以前的。

微軟文檔使用的工具是 docfx ，這是一個很好的工具。

本文將告訴大家如何使用這個工具做出和微軟一樣的文檔

下載

第一步是下載，下載地址是 https://github.com/dotnet/docfx/releases 如果覺得github下載太慢，可以下載我上傳的：http://download.csdn.net/detail/lindexi_gd/9839609

安裝

下載之后需要解壓到軟件運行的文件夾，假如一般放軟件的是在 E:軟件 ，就可以把他解壓到這里。

假設解壓到 E:軟件docfx

在使用之前需要確定已經安裝.NET Core和Microsoft .NET Framework 4.6

環境變量

因為這個軟件是命令行，所以希望在任何都可以使用，添加軟件到環境變量

    setx PATH "%PATH%;E:軟件docfx"

創建文檔文件

首先創建一個文件夾，用來放臨時文件

這里使用的文件夾是D:docfx_walkthrough

然后使用cmd進入這個文件夾。

簡單的方法是地址輸入就好，不需要打開cmd一點進入

在cmd輸入命令 docfx init -q 后面的參數是表示快速，如果希望讓他問你，你自己寫設置，那么就不要加參數。

輸入這個命令會生成docfx_project，這里就是新建的文件，可以看到 docfx.json

這個文件就是設置文件，可以打開看一下

生成文檔

現在就可以進行生成文檔了，因為默認就有一些文檔。

我也覺得快點讓你看到這個工具如何使用才是好的，不需要做太多步就可以看到自己弄出來的網站，這個感覺一般還是很好。

在cmd輸入下面命令，因為這里的 cmd 沒進入 docfx_project ，路徑就是這樣

    docfx docfx_project/docfx.json

可以看到創建了 _site ，這里就是網頁，但是本地查看網頁不太好，來使用自帶的方法。

查看文檔

這個工具可以讓你從瀏覽器看到自己的文檔，使用方法是在cmd輸入代碼

    docfx serve docfx_project/_site

打開 http://localhost:8080 就可以看到網站啦。

注意，如果你的 8080 端口被占用，可以自己定義打開的哪個

    docfx serve docfx_project/_site  -p 可以用端口

添加文檔

現在讓我們添加自己的文檔

打開 articles 文件夾，添加自己的文檔，這里添加

    win10 uwp MVVM入門.md

    win10-uwp-快捷鍵.md

打開 articles 的 toc.yml ，把文件添加進來

- name: win10 uwp MVVM入門
  href: win10 uwp MVVM入門.md
- name: win10-uwp-快捷鍵
  href: win10-uwp-快捷鍵.md

現在已經做好啦

重復 生成文檔 和 查看文檔 文檔兩步。

首先關閉 cmd 再打開，生成文檔

    docfx.exe ./docfx.json

查看文檔

    docfx serve _site -p 1560

打開 http://localhost:1560/ 就可以看到

可以看到添加文檔需要自己寫目錄，這個不是很好，所以我就寫了一個工具來生成。

添加代碼文檔

api文檔是主要的，生成api文檔需要安裝vs2015以上。

首先進入工程，這里進入工程C:程序uwpuwpsrcFrameworkwpfMill

接著使用docfx metadata添加 *.sln

這里使用的是 csproj，兩個都是支持的

    docfx metadata ./wpfMill.csproj

可以看到文件夾多了 _api

把他剪切到剛才的臨時文件

這里是D:docfx_walkthrough，現在的臨時文件看起來是

把 _api 所有文件放到 api

打開 D:docfx_walkthrough oc.yml

- name: Articles
  href: articles/
- name: Api Documentation
  href: api/
  homepage: api/index.md

刪除得到

- name: Articles
  href: articles/
- name: Api Documentation
  href: api/    

然后重復 生成文檔 和 查看文檔 文檔兩步

打開 代碼文檔 看到

左邊和右邊看起來還是很好

做自己的修改

我也覺得現在還沒有那好，因為圖標

默認的有 default iframe.html statictoc

導入微軟的代碼docfx template export 要哪個

   docfx template export default

可以看到多了 _exported_templates 文件

修改他的名字template 然后把 default 所有文件拿出來，放在這個文件里面。

打開docfx.json 修改默認使用的

        "template": [
      "default"
    ]

修改之后

        "template": [
      "template"
    ]

然后修改 template 的圖標

現在看起來很好了，但是需要繼續修改，可以打開 partials

這里就是所有可以修改的樣式

下面來說一個例子：

打開 footer.tmpl.partial

    {{!Copyright (c) Microsoft. All rights reserved. Licensed under the MIT license. See LICENSE file in the project root for full license information.}}

<footer>
  <div class="grad-bottom"></div>
  <div class="footer">
    <div class="container">
      <span class="pull-right">
        <a href="#top">Back to top</a>
      </span>
      {{{_appFooter}}}
      {{^_appFooter}}<span>Copyright ? 2015-2017 Microsoft<br>Generated by <strong>DocFX</strong></span>{{/_appFooter}}
    </div>
  </div>
</footer>

把微軟改為自己名字

    {{!Copyright (c) Microsoft. All rights reserved. Licensed under the MIT license. See LICENSE file in the project root for full license information.}}

<footer>
  <div class="grad-bottom"></div>
  <div class="footer">
    <div class="container">
      <span class="pull-right">
        <a href="#top">Back to top</a>
      </span>
      {{{_appFooter}}}
      {{^_appFooter}}<span>Copyright ? 2015-2017 lindexi<br>Generated by <strong>DocFX</strong></span>{{/_appFooter}}
    </div>
  </div>
</footer>

重新生成文檔，就可以看到，頁面變化了

忽略不使用的api

經常有一些api是不希望顯示在文檔的。

可以忽略的方法有兩個：第一個方法是在生成時添加忽略文件

    docfx.exe metadata -filter 忽略配置文件所在的路徑

忽略文件的路徑可以是相對的。

第二個方法是寫在 docfx.json

添加一個屬性 filter ，假如使用的忽略文件是 filterConfig.yml ，那么現在的文件就可以看到如下面代碼

    {
  "metadata": [
    {
      "src": [
        {
          "files": [
            "src/**.csproj"
          ],
          "exclude": [
            "**/bin/**",
            "**/obj/**"
          ]
        }
      ],
      "dest": "obj/api",
      "filter": "filterConfig.yml"
    }
  ]
}

接下來就是如何寫 filterConfig.yml 。

這個文件可以包含包括的文件和不包括的，包括的權限比不包括大，默認是包括所有文件

包括的文件使用include 不包括使用 exclude ，看起來的文件是

  - include:
      uidRegex: ^Microsoft.DevDiv.SpecialCase
  - exclude:
      uidRegex: ^Microsoft.DevDiv

因為 uidRegex 是匹配，所以對于.需要加上\

強大的ms還可以匹配是什么類型，提供的：

Namespace
Type
Class
Struct
Enum
Interface
Delegate
Member
Event
Field
Method
Property

如果要忽略命名空間是 lindexi.laji 的代碼，請看下面代碼

      - exclude:
         uidRegex: ^lindexi.laji
         type: Namespace

原文：http://dotnet.github.io/docfx/index.html

繼續在微軟上開發

可以看到現在的 docfx 還不夠好，于是我繼續在微軟做的上面開發。

我需要在一個文件夾包含多個項目的情況下，以及包含多個文件夾，里面包含多個項目的情況，可以解析出他們的文檔和代碼。

我想到的做法是在需要轉換的文件夾添加一個文件，這個文件就是配置文件，表示這個文件夾內有哪些文件夾是代碼，哪些是文檔。對于代碼的，需要有哪些是忽略的。

于是程序就獲取配置的文件，從文件獲取到存在哪些文件夾是需要進行轉換的。

然后 遍歷整個文件夾，獲取文件夾里的配置，從而得到需要進行做的文件夾。

如果文件夾里的配置出錯了，如找不到文件或其他的錯誤，那么報告為警告就好。

程序可以從所有的文件夾獲取配置，如果一個文件夾存在配置文件：

docfx.json

那么讀取配置文件里存在哪些配置文件，其中，文件的格式為：

Src:
- E:12
Doc: E:123123
DocfxFolder:
- E:文件夾1
- E:文件夾2

    class Docfx
    {
        /// <summary>
        /// 代碼所在的文件
        /// </summary>
        public List<string> Src
        {
            get; set;
        }

        /// <summary>
        /// 文檔所在的文件夾
        /// </summary>
        public string Doc
        {
            get; set;
        }

        /// <summary>
        /// 包含需要進行文檔的文件夾
        /// <remarks><para>如我有兩個文件夾在不同路徑，那么可以在這里寫這兩個文件夾</para>
        /// 或我把這個文件放在和本程序相同的路徑，用這個文件來說明我需要轉換的文件
        /// </remarks>
        /// </summary>
        public List<string> DocfxFolder
        {
            get; set;
        }
    }

一般可以使用一個配置告訴程序，需要把幾個項目的文檔放在一個文件夾里，這樣可以做搜索比較好。

于是這個配置就是只有 DocfxFolder 一個屬性。一般不可以在使用 DocfxFolder 之后使用 Src 等屬性。但是我這里沒有做要求，只是判斷如果存在 DocfxFolder 就不去讀其他屬性。

可以允許只有三個屬性的一個。

本作品采用知識共享署名-非商業性使用-相同方式共享 4.0 國際許可協議進行許可。歡迎轉載、使用、重新發布，但務必保留文章署名林德熙(包含鏈接:http://blog.csdn.net/lindexi_gd )，不得用于商業目的，基于本文修改后的作品務必以相同的許可發布。如有任何疑問，請與我聯系。

總結

以上是生活随笔為你收集整理的docfx 做一个和微软一样的文档平台的全部內容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網站內容還不錯，歡迎將生活随笔推薦給好友。