docfx 作一個和微軟同樣的文檔平臺

https://blog.csdn.net/lindexi_gd/article/details/78661304

 

c#（166） 

版權聲明：http://blog.csdn.net/lindexi_gd 本文爲博主原創文章，未經博主容許不得轉載。 https://blog.csdn.net/lindexi_gd/article/details/78661304

 

目錄(?)[+]

 

開發中，有一句話叫 最不喜歡的是寫文檔，最不喜歡的是看別人家代碼沒有文檔。那麼世界上文檔寫最 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\"

• 1

建立文檔文件

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

這裏使用的文件夾是D:\docfx_walkthrough

而後使用cmd進入這個文件夾。

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

在cmd輸入命令 docfx init -q 後面的參數是表示快速，若是但願讓他問你，你本身寫設置，那麼就不要加參數。

輸入這個命令會生成docfx_project，這裏就是新建的文件，能夠看到 docfx.json

這個文件就是設置文件，能夠打開看一下

生成文檔

如今就能夠進行生成文檔了，由於默認就有一些文檔。

我也以爲快點讓你看到這個工具如何使用纔是好的，不須要作太多步就能夠看到本身弄出來的網站，這個感受通常仍是很好。

在cmd輸入下面命令，由於這裏的 cmd 沒進入 docfx_project ，路徑就是這樣

docfx docfx_project/docfx.json

• 1

能夠看到建立了 _site ，這裏就是網頁，可是本地查看網頁不太好，來使用自帶的方法。

查看文檔

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

docfx serve docfx_project/_site

• 1

打開 http://localhost:8080 就能夠看到網站啦。

注意，若是你的 8080 端口被佔用，能夠本身定義打開的哪一個

docfx serve docfx_project/_site  -p 能夠用端口

• 1

添加文檔

如今讓咱們添加本身的文檔

打開 articles 文件夾，添加本身的文檔，這裏添加

win10 uwp MVVM入門.md win10-uwp-快捷鍵.md

• 1
• 2
• 3

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

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

• 1
• 2
• 3
• 4
• 5

如今已經作好啦

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

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

docfx.exe ./docfx.json

• 1

查看文檔

docfx serve _site -p 1560

• 1

打開 http://localhost:1560/ 就能夠看到

能夠看到添加文檔須要本身寫目錄，這個不是很好，因此我就寫了一個工具來生成。

添加代碼文檔

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

首先進入工程，這裏進入工程C:\程序\uwp\uwp\src\Framework\wpfMill

接着使用docfx metadata添加 *.sln

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

docfx metadata ./wpfMill.csproj

• 1

能夠看到文件夾多了 _api

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

這裏是D:\docfx_walkthrough，如今的臨時文件看起來是

把 _api 全部文件放到 api

打開 D:\docfx_walkthrough\toc.yml

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

• 1
• 2
• 3
• 4
• 5

刪除獲得

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

• 1
• 2
• 3
• 4

而後重複 生成文檔 和 查看文檔 文檔兩步

打開 代碼文檔 看到

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

作本身的修改

我也以爲如今尚未那好，由於圖標

默認的有 default iframe.html statictoc

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

docfx template export default

• 1

能夠看到多了 _exported_templates 文件

修改他的名字template 而後把 default 全部文件拿出來，放在這個文件裏面。

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

"template": [ "default" ]

• 1
• 2
• 3

修改以後

"template": [ "template" ]

• 1
• 2
• 3

而後修改 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> 

• 1
• 2
• 3
• 4
• 5
• 6
• 7
• 8
• 9
• 10
• 11
• 12
• 13
• 14
• 15

把微軟改成本身名字

 {{!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> 

• 1
• 2
• 3
• 4
• 5
• 6
• 7
• 8
• 9
• 10
• 11
• 12
• 13
• 14
• 15

從新生成文檔，就能夠看到，頁面變化了

忽略不使用的api

常常有一些api是不但願顯示在文檔的。

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

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

• 1

忽略文件的路徑能夠是相對的。

第二個方法是寫在 docfx.json

添加一個屬性 filter ，假如使用的忽略文件是 filterConfig.yml ，那麼如今的文件就能夠看到以下面代碼

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

• 1
• 2
• 3
• 4
• 5
• 6
• 7
• 8
• 9
• 10
• 11
• 12
• 13
• 14
• 15
• 16
• 17
• 18
• 19

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

這個文件能夠包含包括的文件和不包括的，包括的權限比不包括大，默認是包括全部文件

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

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

• 1
• 2
• 3
• 4
• 5

由於 uidRegex 是匹配，因此對於.須要加上\\

強大的ms還能夠匹配是什麼類型，提供的：

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

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

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

• 1
• 2
• 3

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

繼續在微軟上開發

能夠看到如今的 docfx 還不夠好，因而我繼續在微軟作的上面開發。

我須要在一個文件夾包含多個項目的狀況下，以及包含多個文件夾，裏面包含多個項目的狀況，能夠解析出他們的文檔和代碼。

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

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

而後 遍歷整個文件夾，獲取文件夾裏的配置，從而獲得須要進行作的文件夾。

若是文件夾裏的配置出錯了，如找不到文件或其餘的錯誤，那麼報告爲警告就好。

程序能夠從全部的文件夾獲取配置，若是一個文件夾存在配置文件：

docfx.json

那麼讀取配置文件裏存在哪些配置文件，其中，文件的格式爲：

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

• 1
• 2
• 3
• 4
• 5
• 6

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; } } 

• 1
• 2
• 3
• 4
• 5
• 6
• 7
• 8
• 9
• 10
• 11
• 12
• 13
• 14
• 15
• 16
• 17
• 18
• 19
• 20
• 21
• 22
• 23
• 24
• 25
• 26
• 27
• 28
• 29
• 30

通常可使用一個配置告訴程序，須要把幾個項目的文檔放在一個文件夾裏，這樣能夠作搜索比較好。

因而這個配置就是隻有 DocfxFolder 一個屬性。通常不能夠在使用 DocfxFolder 以後使用 Src 等屬性。可是我這裏沒有作要求，只是判斷若是存在 DocfxFolder 就不去讀其餘屬性。

能夠容許只有三個屬性的一個。

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