.NET6使用DOCFX根据注释自动生成开发文档
本文內容來自我寫的開源電子書《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-pickhref: GIT 的merge、rebase和cherry-pick.md - name: Google Fonts注意事項href: Google Fonts注意事項.md - name: issue trans Problem Descriptionhref: 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: Articleshref: ../articles/toc.yml - name: Bloghref: ../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: Articleshref: ../articles/toc.yml - name: Bloghref: ../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:commondefault(zh-cn)defaultpdf.defaultstatictoc可以在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
已將所有引用其他文章之內容清楚明白地標注,其他部分皆為作者勞動成果。對作者勞動成果做以下聲明:
copyright ? 2021 蘇月晟,版權所有。
本作品由蘇月晟采用知識共享署名-非商業性使用-相同方式共享 4.0 國際許可協議進行許可。
本文作者:蘇月晟,轉載請注明原文鏈接:https://www.cnblogs.com/sogeisetsu/p/15674507.html
我的開源電子書《WoW C#》正在編寫中,歡迎去https://git.io/JMlrA 關注、批評和指導。
總結
以上是生活随笔為你收集整理的.NET6使用DOCFX根据注释自动生成开发文档的全部內容,希望文章能夠幫你解決所遇到的問題。
- 上一篇: 高效的动态URL限流实现
- 下一篇: 黄老师离开呆了十年的上海