.NET6使用DOCFX自動生成開發文件

sogeisetsu發表於2021-12-11

本文內容來自我寫的開源電子書《WoW C#》，現在正在編寫中，可以去WOW-Csharp/學習路徑總結.md at master · sogeisetsu/WOW-Csharp (github.com)來檢視編寫進度。預計2021年年底會完成編寫，2022年2月之前會完成所有的校對和轉制電子書工作，爭取能夠在2022年將此書上架亞馬遜。編寫此書的目的是因為目前.NET市場相對低迷，很多優秀的書都是基於.NET framework框架編寫的，與現在的.NET 6相差太大，正規的.NET 5學習教程現在幾乎只有MSDN，可是MSDN雖然準確優美但是太過瑣碎，沒有過閱讀開發文件的同學容易一頭霧水，於是，我就編寫了基於.NET 5的《WoW C#》。本人水平有限，歡迎大家去本書的開源倉庫sogeisetsu/WOW-Csharp關注、批評、建議和指導。

注意，本文所講的API，為基於對程式碼註釋而自動生成的開發文件，API內容為程式碼中內類及成員的解釋，並非Web API或者REST API。

DOCFX

在團隊開發過程中，一個漂亮的開發文件是至關重要的，它有助於幫助人們快速地理解專案。DOCFX是一個搭建開發文件網站和根據註釋生成api文件的工具。DOCFX極其強大，自定義程度極高，缺點是自動化程度不高，使用起來略顯麻煩，比如已經2021年了，官方竟然還不支援自動生成目錄，好在其有很多與其相關的開源專案，可以一定程度上彌補它的缺憾。如果將DOCFX用好了，它就不僅僅是API文件生成器，還是一個簡單的部落格網站構建器，DOCFX由微軟旗下的dotnet開源，微軟的MSDN的構建就用到了DOCFX。遺憾的是DOCFX目前官方只支援.Net和JavaScript，但是它提供了Generate Metadata的步驟，理論上它可以支援任何語言（DocFX is designed to support any language），GitHub上基本上常見的語言都有針對DOCFX的開源專案。本文對DOCFX的講解不及其功能的十分之一，但是基本上可以應對日常的需要，如果想要進一步瞭解DOCFX，請前往DocFX - static documentation generator | DocFX website (dotnet.github.io)。本文所使用由DOCFX生成的API文件專案可以前往sogeisetsu/WOW-Csharp at docfx_example (github.com)檢視原始碼。

第一步生成簡單的文件網站

前往Releases · dotnet/docfx (github.com)下載最新版的DOCFX。將其加入環境變數，這樣為了方便起見，docfx 命令可以直接從任何地方呼叫。(例如，對於 Windows，設定 PATH =%PATH%;d:docfx)。

執行docfx init-q。這個命令生成一個 docfx_project 資料夾，其下面有預設的 docfx.json 檔案。Json 是 docfx 用來生成文件的配置檔案。-q 選項意味著使用預設值悄悄地生成專案，您也可以嘗試 docfx init，並按照說明提供自己的設定。
執行命令 docfx docfx_project/docfx.json。請注意，在該資料夾下生成了一個新的子資料夾 _site。這是生成靜態網站的地方。
執行docfx serve docfx_project/_site就可以從http://localhost:8080檢視生成的網頁。如果未使用埠 8080，docfx 將在 http://localhost:8080 下託管 _site。如果8080正在使用，可以使用docfx serve _site -p <port>更改docfx使用的埠。

向網站新增文章

在進行初始化和建立網站之後，當前的docfx_project檔案結構應該是這樣的：

.
├── _site
├── api
├── apidoc
├── articles
├── docfx.json
├── images
├── index.md
├── obj
├── src
└── toc.yml

各個檔案和資料夾的作用如下：

/ - 這個網站的根目錄，包含:

docfx.json - docfx 依賴的配置檔案。所有的命令及其涉及到的檔案都會用docfx.json來配置。
index.md - 用來建立網站的首頁。
toc.yml – 呈現為導航選單欄，顯示在網站每個頁面的頂部。

/articles - 裡面放著一些markdown檔案。這些markdown檔案的圖片放在/images下。這些 Markdown 檔案釋出在選單欄的Ariticles部分下。

/src - 包含可選的 .NET 語言專案檔案 (*.csproj)，其中包含用於生成託管 API 文件的型別資訊。

/apidoc - 包含用於覆蓋根據註釋中自動生成的文字的 Markdown 檔案。

執行 DocFx 後，將建立其他資料夾：

/_site - 包含由 DocFx 生成的所有站點檔案，包括網站所需的生成的 HTML/JSON/JS/Images 檔案。

修改首頁

可以修改根目錄下的index.md來修改網站的首頁

將更多的文章放到網站

將更多.md檔案放入articles，例如快速開始.md，演練.md，進階.md。如果檔案引用了任何資源，請將這些資源放入images資料夾中。
為了組織這些文章，我們將這些檔案新增到/articles/toc.yml（也可以使用工具Release 用於自動生成docfx文件 · whuanle/CZGL.DocfxBuild.Yml (github.com)自動生成目錄）。內容toc.yml如下：
```
- name: 快速開始
  href: intro.md
- name: 演練
  href: 演練.md
- name: 進階
  href: 進階.md
```
現在articles資料夾的佈局是：
```
.
├── intro.md
├── toc.yml
├── 演練.md
└── 進階.md
```
在docfx_project資料夾下執行docfx和docfx serve _site，然後就可以看到已經有文章加入:

修改導航選單欄

導航選單欄預設有兩個選項，分別是Articles和API Documentation，可以通過修改根目錄下的toc.yml來修改導航選單欄的名稱：

- name: 開始
  href: articles/
- name: Api 文件
  href: api/
  # homepage來定義api的首頁
  homepage: api/index.md

也可以嚮導航選單欄增加新的選項，比如說，在根目錄新建一個資料夾，命名為blog，該資料夾結構如下：

.
├── GIT 的merge、rebase和cherry-pick.md
├── Google Fonts注意事項.md
├── Linux筆記.md
├── issue trans Problem Description.md
├── python 包（package）和模組（module）的建立和引入（import）.md
├── toc.yml
├── unix bsd linux shell bash GNU之間的聯絡，歪講Linux(一).md
├── vscode git 無需命令列.md
├── 一.md
├── 關於若干問題的解釋說明.md
├── 商品上架格式.md
├── 如何在印刷品中使用遵循SIL Open Font License協議的字型.md
├── 對微信支付文件的自我理解.md
├── 我的python加密方案.md
├── 找人.md
├── 日語 時間的量.md
├── 日語學習資源的分享.md
├── 說明.md
├── 貝多芬小傳.md
├── 還沒有學會告別，就已經後會無期。.md
├── 雷電介面.md
└── 青島科技大學新生報考參考.md

在該資料夾內新增toc.yml，內容如下：

### D:\blog
- name: GIT 的merge、rebase和cherry-pick
  href: GIT 的merge、rebase和cherry-pick.md
- name: Google Fonts注意事項
  href: Google Fonts注意事項.md
- name: issue trans Problem Description
  href: issue trans Problem Description.md
- name: Linux筆記
  href: Linux筆記.md
- name: python 包（package）和模組（module）的建立和引入（import）
  href: python 包（package）和模組（module）的建立和引入（import）.md
- name: unix bsd linux shell bash GNU之間的聯絡，歪講Linux(一)
  href: unix bsd linux shell bash GNU之間的聯絡，歪講Linux(一).md
- name: vscode git 無需命令列
  href: vscode git 無需命令列.md
- name: 一
  href: 一.md
- name: 關於若干問題的解釋說明
  href: 關於若干問題的解釋說明.md
- name: 商品上架格式
  href: 商品上架格式.md
- name: 如何在印刷品中使用遵循SIL Open Font License協議的字型
  href: 如何在印刷品中使用遵循SIL Open Font License協議的字型.md
- name: 對微信支付文件的自我理解
  href: 對微信支付文件的自我理解.md
- name: 我的python加密方案
  href: 我的python加密方案.md
- name: 找人
  href: 找人.md
- name: 日語 時間的量
  href: 日語 時間的量.md
- name: 日語學習資源的分享
  href: 日語學習資源的分享.md
- name: 說明
  href: 說明.md
- name: 貝多芬小傳
  href: 貝多芬小傳.md
- name: 還沒有學會告別，就已經後會無期。
  href: 還沒有學會告別，就已經後會無期。.md
- name: 雷電介面
  href: 雷電介面.md
- name: 青島科技大學新生報考參考
  href: 青島科技大學新生報考參考.md

修改根目錄的toc.yml，將blog資料夾加進去：

- name: 開始
  href: articles/
- name: Api 文件
  href: api/
  homepage: api/index.md
- name: 部落格
  href: blog/
  homepage: blog/GIT 的merge、rebase和cherry-pick.md

然後修改根目錄下的docfx.json，這是依賴的配置檔案。關於它的用法後面再講，在docfx.json修改build的content下新增:

{
    "files": [
        "blog/**.md",
        "blog/**/toc.yml",
        "toc.yml",
        "*.md"
    ]
}

在docfx_project資料夾下執行docfx和docfx serve _site，然後就可以看到已經有文章加入:

第二步向網站新增 API 文件

向/src資料夾下新增一個c#專案，要包含csproj檔案。

├── src
   ├── ConsoleApp1.csproj
   ├── Program.cs
   ├── bin
   ├── newLei.cs
   └── obj

在docfx_project資料夾下執行docfx和docfx serve _site，然後就可以看到已經有根據註釋自動生成的API文章加入:

在左側導航加入其他資料夾的內容

當前的根目錄下的toc.yml是這樣的：

- name: 開始
  href: articles/
- name: Api 文件
  href: api/
  homepage: api/index.md
- name: 部落格
  href: blog/
  homepage: blog/GIT 的merge、rebase和cherry-pick.md

這表示開始這一選單下只會包含articles資料夾下面的內容。

現在在根目錄新建一個資料夾，命名為anycombine，在該資料夾下面放置一個toc.yml，內容如下：

- name: Articles
  href: ../articles/toc.yml
- name: Blog
  href: ../blog/toc.yml

然後修改根目錄下的toc.yml：

- name: 開始
  href: anycombine/
- name: Api 文件
  href: api/
  homepage: api/index.md
- name: 部落格
  href: blog/
  homepage: blog/GIT 的merge、rebase和cherry-pick.md

最後在docfx.json裡面新增anycombine資料夾，讓其在建立網頁時能夠包含這個資料夾：

  "build": {
    "content": [
      {
        "files": "anycombine/**"
      },

然後建立網站，網站上導航選單欄中的開始選項包含articles和blog兩個資料夾的內容：

匯出為PDF文件

之前已經講解了如何生成網站，現在講解如何將網站上面的內容轉為PDF，先下載一個開源工具 wkhtmltopdf，可以前往wkhtmltopdf根據自己電腦的規格來選擇版本。安裝或解壓之後，將其放置在環境變數，方便以後呼叫，可以在power shell使用setx PATH "%PATH%;D:\wkhtmltopdf\bin"來將其放入環境變數。

然後在之前docfx生成的資料夾的根目錄下建立一個資料夾，名為pdf，在裡面建立一個toc.yml來包含需要生成PDF的目錄：

- name: Articles
  href: ../articles/toc.yml
- name: Blog
  href: ../blog/toc.yml
- name: API 文件
  href: ../api/toc.yml

接下來，需要將pdf部分新增到docfx.json，只有這樣，才能在執行docfx的時候來將其轉換為pdf，增加一個pdf屬性，在docfx.json排除了 TOC 檔案，因為每個 TOC 檔案都會生成一個 PDF 檔案，內容如下：

"pdf": {
    "content": [
        {
            "files": [
                "api/**.yml"
            ],
            "exclude": [
                "**/toc.yml",
                "**/toc.md"
            ]
        },
        {
            "files": [
                "articles/**.md",
                "articles/**/toc.yml",
                "toc.yml",
                "*.md"
            ],
            "exclude": [
                "**/toc.yml",
                "**/toc.md"
            ]
        },
        {
            "files": [
                "blog/**.md",
                "blog/**/toc.yml",
                "toc.yml",
                "*.md",
                "pdf/*"
            ],
            "exclude": [
                "**/toc.yml",
                "**/toc.md"
            ]
        },
        {
            "files": "pdf/toc.yml"
        }
    ],
    "resource": [
        {
            "files": [
                "images/**"
            ]
        }
    ],
    "overwrite": [
        {
            "files": [
                "apidoc/**.md"
            ],
            "exclude": [
                "obj/**",
                "_site/**"
            ]
        }
    ],
    "wkhtmltopdf": {
        "additionalArguments": "--enable-local-file-access"
    },
    "dest": "_site_pdf"
}

然後在docfx專案的根目錄執行docfx，就可以在_site_pdf資料夾看到pdf檔案了。提示：這一過程可能會花費比較長的時間，建議喝杯咖啡等待。

其實，說實話，html的表現效果一定要比PDF檔案強，這個是毋庸置疑的。

DOCFX 常用命令

現在根據docfx.json中的設定，有下面幾個命令（之所以放到這裡說是因為易懂性方面的考慮）：

docfx metadata 根據src目錄下的專案來修改api資料夾的內容，即生成API文件。
docfx build 生成網站原始碼，檔案放在_site資料夾下。
docfx serve <_site資料夾位置> 建立本地伺服器，可以本地訪問API網站內容
docfx pdf 匯出PDF。
docfx 執行docfx metadata、docfx build和docfx pdf。

應該可以看到，DOCFX的命令的內容甚至是作用都和docfx.json中的配置是息息相關的，這個配置檔案其實很好理解，主要記住content屬性會規定命令會波及到哪些檔案和會放過那些檔案其實就可以了。遇到別的需求可以查閱docfx.exe User Manual | DocFX website (dotnet.github.io)，裡面詳細地記載了docfx.json中每個屬性的作用。

自定義

template

執行命令docfx template list，可看到內建的模板列表：

Existing embedded templates are:
        common
        default(zh-cn)
        default
        pdf.default
        statictoc

可以在docfx.json中的build屬性的template屬性中設定模板：

"template": [
    "default(zh-cn)"
],

也可以在命令列中進行類似-t statictoc的操作，比如使用docfx build -t statictoc之後的網站是一個靜態網站，可以通過本地檔案系統預覽而非伺服器環境。

匯出template

使用docfx template export default可已匯出預設的HTML模板，將有名為 _exported_templates 的資料夾新增到根目錄下，其中包含名為default的資料夾，即default模板的HTML。

建立template

建立一個資料夾，比如templates，然後將匯出的_exported_templates 中的default資料夾複製到templates中。

templates中的default現在就是建立的一個新的模板資料夾，可以修改其中的內容來自定義。
- 修改partials/footer.tmpl.partial來修改頁尾版權，建議只修改<span>Generated by <strong>DocFX</strong></span>部分來宣告自己的版權，不要修改微軟對DOCFX的版權。
```
{{!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">{{__global.backToTop}}</a>
      </span>
      {{{_appFooter}}}
      {{^_appFooter}}<span>Copyright (c) 2021 蘇月晟，版權所有。<br>通過<strong>DocFX</strong>生成</span>{{/_appFooter}}
    </div>
  </div>
</footer>
```
- 有一個預設模板叫做default(zh-cn)，可以將文件改為中文，在docfx.json將其放到裡面來實現中文，並將自定義模板放到default(zh-cn)後面，因為在docfx.json的build的template中是後面的覆蓋前面的，這樣就不用再一個個修改自己自定義的模板了。如果想自定義中文可以修改模板檔案中的partials/title.tmpl.partial和token.json兩個檔案來自定義中文名稱。
```
"template": [
    "templates/default",
    "default(zh-cn)"
],
```
- 對於修改圖示和logo有兩個方式，一個是參考docfx.exe User Manual | DocFX website (dotnet.github.io)在docfx.json中的"globalMetadata"進行修改，另一個是直接替換模板檔案中的logo.svg和favicon.ico。可以修改partials\logo.tmpl.partial來取消class=“svg”從而取消logo的動畫，並可以調整大小，這裡附上我自己對partials\logo.tmpl.partial的修改，僅供參考。
```
<a class="navbar-brand" href="{{_rel}}index.html">
  <img id="logo" src="{{_rel}}{{{_appLogoPath}}}{{^_appLogoPath}}logo.svg{{/_appLogoPath}}" height="46" width="46" alt="{{_appName}}" >
</a>
```
- 可以在docfx.json中的"globalMetadata"將_enableSearch設定為true來增加搜尋框，但是根據實驗，docfx對中文搜尋的支援很差。可以修改_appTitle來修改網站的標題。可以增加_gitContribute來設定Improve this Doc按鈕。
- 可以修改模板中的styles\docfx.vendor.css來自由發揮對css的修改，筆者的方式為先在瀏覽器中確定css選擇器，然後再進行對應的修改。
最終為了使我們建立的模板工作，應當在在docfx.json的build的template中的來新增模板資料夾相對位置，為了顯示中文，筆者還會使用一個預設模板叫做default(zh-cn)。
- ```
"template": [
    "templates/default",
    "default(zh-cn)"
],
```

最終的效果如下：

可以訪問這是首頁 | 演示文件製作 (sogeisetsu.github.io)來檢視在這篇文章中筆者所建立的文件網站，可以在sogeisetsu/WOW-Csharp at docfx_example (github.com)檢視文件網站的原始碼和docfx配置檔案。

LICENSE

已將所有引用其他文章之內容清楚明白地標註，其他部分皆為作者勞動成果。對作者勞動成果做以下宣告：

本作品由蘇月晟採用知識共享署名-非商業性使用-相同方式共享 4.0 國際許可協議進行許可。

自動生成介面文件coreapi
2024-04-18
API
showdoc 自動生成 API 文件
2020-04-02
API
DRF 自動生成介面文件
2022-04-08
利用apidoc自動生成model文件
2019-03-02
API
使用go-swagger為golang API自動生成swagger文件
2018-05-23
SwaggerGolangAPI
如何利用showdoc自動生成API文件
2018-08-20
API
java 文件自動生成的神器 idoc
2021-10-19
Java
node.js自動生成api文件（apidocjs）
2018-10-23
Node.jsAPI
NET 5.0 Swagger API 自動生成MarkDown文件
2021-03-14
SwaggerAPI
怕寫文件？AI自動生成程式碼文件的外掛
2022-02-28
AI
Django（74）drf-spectacular自動生成介面文件
2021-11-02
Django
自動生成為swagger文件的出入參示例
2021-09-09
Swagger
[Django REST framework - 自動生成介面文件、分頁]
2021-07-07
DjangoRESTFramework
Laravel 8 開發中使用 swagger-php 3 生成文件
2021-09-10
LaravelSwaggerPHP
優於 swagger 的 java markdown 文件自動生成框架-01-入門使用
2019-03-18
SwaggerJava框架
Spring boot 之自動生成API文件swagger2
2018-05-16
Spring BootAPISwagger
從Python原始碼註釋，自動生成API文件
2021-10-12
Python原始碼API
IDEA外掛Apifox,一鍵自動生成介面文件！
2023-02-27
IdeaAPI
解放生產力，自動化生成vue元件文件
2021-06-29
Vue元件
爬取Arcconf文件教程並自動生成Gitbook文件顯示 - 資料獲
2021-09-09
Git
BigCode：使用AI自動生成程式碼的開源工具
2022-09-30
GCAI開源工具
使用apidoc文件神器，快速生成api文件
2019-03-04
API
word文件生成影片，自動配音、背景音樂、自動字幕，另類創作工具
2024-06-14
拯救懶癌文件君 - VuePress + Travis CI + Github Pages 自動線上生成文件
2019-06-17
VueGithub
【Python】生成html文件-使用dominate
2024-06-02
PythonHTML
推薦一個軟體自動生成介面文件（帶實現）
2019-03-13
SynProject 介紹---（synopse理解的版本控制和文件自動化生成）
2024-06-10
Project
IOS技術分享| iOS快速生成開發文件（二）
2022-06-30
iOS
IOS技術分享| iOS快速生成開發文件（一）
2022-05-24
iOS
自動生成serialVersionUID
2020-11-21
UI
uuid自動生成
2020-12-06
UI
Laravel-apidoc-generator 無法自動生成帶引數的 API 文件
2019-07-11
LaravelAPI
vue中使用前端庫：nanoid自動生成id
2024-03-31
Vue前端NaN
Django部落格使用Markdown自動生成目錄
2021-03-07
Django
「懶惰的美德」我用 python 寫了個自動生成給文件生成索引的指令碼
2020-12-05
Python索引指令碼
web自動化測試框架-02 快速開發用例文件指令碼
2018-05-29
Web框架指令碼
LeaRun.Java快速開發平臺高效程式碼自動化生成
2022-07-04
Java
使用.NET6打造動態API
2021-11-02
API