.NET6使用DOCFX根據注釋自動生成開發文檔

本文轉載自查看原文 2021-12-11 04:51 933 c#/ 原創/ .NET

本文內容來自我寫的開源電子書《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 國際許可協議進行許可。

免責聲明！

本站轉載的文章為個人學習借鑒使用，本站對版權不負任何法律責任。如果侵犯了您的隱私權益，請聯系本站郵箱yoyou2525@163.com刪除。

猜您在找 DocFX生成PDF文檔 laya的開發文檔開發接口文檔--本接口文檔是讀取控制器方法上的注釋自動生成的 idea自動生成文檔注釋翻譯-ExcelDNA開發文檔 phpredis中文開發文檔 cinatra中文開發文檔試試使用 eolinker 掃描 GitLab 代碼注釋自動生成 API 文檔？ iOS開發-開發文檔安裝人人快速開發平台開發文檔