一、簡介
Docfx 是微軟開發的一款開源的文檔生成工具,其預設支援 C# 與 VB.Net 這兩種項目的文檔生成,支援 DotNetCore 項目,并且還可以打包成一個靜态的 Web 站點,而且還支援 markdown 檔案。
這個站點就是 ImageSharp 的 API 文檔,可以去參考一下。
二、安裝
下載下傳
Docfx 是即開即用的,他基于 .Net Framework 開發,是以我們可以先在 Windows 平台上面生成 API 文檔試一下,DocFx 的下載下傳位址為 https://github.com/dotnet/docfx/releases ,選擇最新版本下載下傳即可。
設定環境變量
然後解壓其壓縮包,因為這是一個指令行程式,是以我們可以将其目錄添加到環境變量以便于我們在任何地方來使用。
按住 Shift 鍵再點選右鍵在目前目錄彈出 cmd 指令行視窗,輸入一下指令:
setx PATH "%Path%;< 這裡是你 docfx.exe 所在的目錄>"
三、使用
初始化基礎項目
在你需要生成基礎項目的檔案夾下打開指令行視窗,運作
docfx init -q
就回在目前目錄下生成一個 docfx_project 檔案夾,這裡面包含了一些基本配置,稍後再講。
生成 API yml 檔案
docfx 支援為 csproj 與 sln 來生成 API 文檔,假如你的庫有很多個的話,就可以直接根據 sln 解決方案來生成 API 文檔。
我們來到 API 目錄下面,在 csproj 檔案所在目錄打開指令行視窗,運作
docfx metadata ./api.csproj
指令就會在這個目錄下面生成一個 _api 檔案夾,這裡面會包含大量像這樣的 yml 檔案。
将這些檔案拷貝到 docfx_project 目錄下的 api 檔案夾内,編輯 docfx_project 根目錄的 toc.yml 檔案,如下:
這裡面就是管理 API 站點目錄結構的,可以看到這裡的每一個以
-
劃分的都是一個節點,也就是在 API 站點頂部導航欄所展示的内容,而
href
則是該導航欄指向的文檔目錄路徑。
homepage
則是首頁的 markdown 檔案。
如果你有一些自定義的文檔則可以在這裡添加目錄結構。
建構 API 站點
檔案這些已經準備就緒,原始的站點文檔都以 yml 檔案與 md 檔案為主,我們可以通過調用
docfx ./docfx.json
指令來将這些檔案建構成一個靜态的 html 站點。
預覽 API 站點
如果我們想檢視效果的話,可以在 docfx_project 目錄執行
docfx serve ./_site
指令,它将會開啟一個伺服器,你也可以通過
-p
參數來指定自己的端口,例如
docfx serve ./_site -p 5000
。
四、部署
如果隻是自己看就沒什麼用了,那麼我們還可以通過 Docker 來将我們的站點部署到伺服器上,如何來做呢?大緻思路就是一個 docker 鏡像生成
_site
檔案夾,一個鏡像來做 Web 伺服器承載站點。
制作鏡像
1.文檔生成鏡像 doc_generator
那麼我們首先來編寫生成 docker 鏡像的 Dockerfile 檔案:
FROM mono:latest
WORKDIR /work
COPY ./ .
# 建構 API 站點
RUN mono /work/docfx/docfx.exe /work/docfx.json \
&& mkdir /app
ENTRYPOINT ["cp","-r","/work/_site/*","/app"]
運作
docker build -t doc_generator .
指令生成了一個 doc_generator 鏡像。
2.Web 伺服器鏡像 nginx
這裡 Web 伺服器鏡像并不需要特别的定制,直接使用 nginx 的預設鏡像就可以了。
運作鏡像
那麼我們來編寫一個 Shell 運作我們的鏡像:
#!/bin/bash
docker run -dti -v /temp/document_html:/app --name=doc_generator doc_generator
# 移動檔案,更改檔案目錄結構
cp -r /temp/document_html/_site/* /temp/document_html
docker run --name=doc_nginx -d -p 20001:80 -v /temp/document_html:/usr/share/nginx/html nginx
執行腳本之後檢視效果:
五、後記
結合 Jenkins 等 CI 你可以實作自動增量更新,這裡就不再贅述了。