熊貓克里斯

PandaChris of an Agile Developer

2016-04-23

【Jenkins 建置程序】DocFx 整合至 Jenkins

DocFx 文件生成工具，整合至 Jenkins。

DocFx 文件產生器

A documentationl generation toll for API referecnce and markdown files !

詳細的套件安裝與介紹，可以參考 Jamis Liao 大大的文章

會得知這一套好用的套件，也是看到 Jamis Liao 的部落格

https://goo.gl/ufDmsf （天橋下的說書人）

這篇主要是記錄 DocFx 如何整合至 Jenkins

 

docfx.msbuild for Visual Studio

專案安裝完 docfx.msbuild 套件後，會整合至 msbuild

當你的專案建置時，會使用 docfx.exe 執行 docfx.json 去搜尋專案的 source code（分析 dll 檔）

一併幫您產生 DocFx 文件

 

DocFx 自動生成的文件（ 會變動的 ）

_site : Html Report 的主要資料夾，完整的 API document

obj : 存放生成文件所需的 yml 檔，YAML 是一種 metadata format（ docfx 使用 ）

log : 每次建置的 log 記錄

 

docfx.json DocFx sub-command 描述所要執行的指令

docfx.json：Generate metadata for the C# project，內含指令描述，告訴 docfx.exe 要執行哪些動作

其他沒特別說明的檔案，都是一些 DocFx 的 .md 說明檔。

 

 DocFx 整合至 Jenkins 步驟

  • 從版本控管取得 source code
  • MSBuild 建置一併產生 DocFx 文件
  • 利用 MSBuild 將網站發行至 IIS
  • 不安裝 docfx.msbuild，自行執行 docfx.exe 產生文件

 

1. 從版本控管取得 source code

Repositories

此次範例是使用 GitHub 版控，先準備一個 GitHub 的 Repositories

專案是使用 APS .NET MVC 範本專案 ，記得到『管理 NuGet 套件』安裝 docfx.msbuild，並 push 到上面建的 GitHub Repositories

 

JenKins Setting

在 Jenkins 作業 =>  組態 => 原始碼管理（事先準備：需要先在 Git Plugin 設定帳號密碼，才能取 source code ）

 

 2. MSBuild 建置一併產生 DocFx 文件

JenKins Setting

若您的專案有安裝 docfx.msbuild，在執行 Nuget 套件還原時，就會自動產生所需的環境

nuget restore

執行 MSBuild.exe 就會一併產生 DocFx 文件（事前準備：要安裝 MSBuild，如果你有安裝 Visual Studio 幾乎都有了）

"C:\Program Files (x86)\MSBuild\14.0\Bin\amd64\MSBuild.exe" DocFxForJenkinsDemo.sln

儲存，並點擊『馬上建置』，確認在你 Jenkins server 上，作業的 workspace 資料夾下，是否有正確生成 _site 資料夾

 

3. 利用 MSBuild 將網站發行至 IIS

IIS

先在 IIS Server 上建立一個 website（事先準備：IIS 必須要安裝 WebDeploy 3.5 以上版本，並允許遠端發行）

 

Visual Studio

在專案按下右鍵 => 發行，新建並設定發行設定檔。

嘗試直接在 Visual Studio 發行，確定可以發行到上面所建立的網站，並且網站可以正常運作

到這邊發行的網站是沒有 DocFx 文件的，因為專案安裝完 docfx.msbuild 後

產生的主要資料夾 _site 是沒有加入至專案的（ 隱藏 ），所以並不會發行到網站

把 _site 加入至專案，再發行一次

在 url 最後面加上 /_site，就會出現 DocFx 文件了

最後記得再把專案 push 到 GItHub Repositories，讓 Jenkins 在取得 source code 可以拿到發行設定檔

 

JenKins Setting

將上述 Visual Studio 所做的發行動作，轉為 command line 指令執行

cd DocFxForJenkinsDemo
"C:\Program Files (x86)\MSBuild\14.0\Bin\amd64\MSBuild.exe" /p:Configuration=Debug /p:Platform="AnyCPU" /p:DeployOnBuild=true /p:PublishProfile="DocFxForJenkinsLocal" /p:AllowUntrustedCertificate=True DocFxForJenkinsDemo.csproj

 存檔，點擊『馬上建置』，作業成功表示，已成功發行。

 

4. 不安裝 docfx.msbuild，自行執行 docfx.exe 產生文件

完成上述步驟，基本上已經成功將 DocFx 整合至 Jenkins 了

但因為專案安裝了 docfx.msbuild ，導致每一次 在 Visual Studio Build 時

都會跑一次 docfx.exe 去更新文件，建置的時間會隨著專案 source code 的成長一併增加

以目前我們正在開發的專案，Build 一次都要一分多鐘，真的是很久呀！

所以還是交給 Jenkins 來做

 

下載 docfx.exe

先到 https://github.com/dotnet/docfx/releases 下載最新版本 docfx.zip

解壓縮到 Jenkins Server 主機上，主要目的是能讓 Jenkins 執行檔 docfx.exe

 

Visual Studio 移除 docfx.msbuild

但先別急著移除，先到專案資料夾下，將下圖標記的資料夾及檔案，先複製出來。（以防發行設定檔有勾選，移除目的地上的其他檔案）

移除 docfx.msbuild，將專案 push 到 GItHub Repositories。

 

JenKins Setting

因為專案已經移除了 docfx.msbuild 所以 nuget 套件還原後，並不會有 docfx.exe 檔

MSBuild 也不會執行 docfx.exe，所以要自行加入指令來執行 docfx.exe

 

完整的 JenKins Setting

  • 原始碼管理 Git：輸入 Repository URL 取得 source code
  • MSBuild：nuget 套件還原，建置專案
    • nuget restore
    • "C:\Program Files (x86)\MSBuild\14.0\Bin\amd64\MSBuild.exe" DocFxForJenkinsDemo.sln
  • DocFx：執行 docfx.exe 產生文件
    • cd DocFxForJenkinsDemo
    • "C:\tool\docfx\docfx.exe"
  • WebDeploy：使用 MSBuild DeployOnBuild 發行網站
    • cd DocFxForJenkinsDemo
    • "C:\Program Files (x86)\MSBuild\14.0\Bin\amd64\MSBuild.exe" /p:Configuration=Debug /p:Platform="AnyCPU" /p:DeployOnBuild=true /p:PublishProfile="DocFxForJenkinsLocal" /p:AllowUntrustedCertificate=True DocFxForJenkinsDemo.csproj

 

結語

  • DocFx 所產出來的文件，算是非常的完整，排版以及搜尋功能都是非常的清楚，很好找資料
  • 雖然產出 DocFx 文件需要一些時間，但交給 JenKins 執行後，就方便多了
  • 整合至 CI 程序，自動產生漂亮的文件，也能激勵大家多寫 source code 的 summary
  • 人總是健忘的，有完整的 living document，是很幸福的一件事

 

參考資料

 

本頁段落