使用 Sandcastle Help File Builder 產生 .NET Library 說明文件

在開發專案時,程式人員最不喜歡的無非是:

  • 寫文件。
  • 對方沒寫文件。
  • 心裡OS:「寫Code都來不及,還要同步維護文件」,導致文件就這樣爛了....

因為上述不少的問題下,Live Document 需求就由然而生。

我們期望找到「依據實際的Code與註解,來動態產生文件」的方法;接下來就來說明如何實作。

前言

無論是公司 or 小團隊的專案,缺少相關文件說明時,會讓大家在使用上多少不便,尤其底層元件運用頻繁,更需要使用文件來協助開發。
而文件內容,我們希望依據現有專案Code來動態產生;這樣的文件可以反應真實情況,且不怕年久失修。因為有以上原因,所以開始進行評估作業。

提醒:這個解決方案為紀錄與分享類別庫專案的文件產生方式。

評估

stackoverflow:C# documentation generator

依據 stackoverflow 上面的推薦;首先選擇了 Sandcastle 這套開源又可免費使用的工具。
需要注意的是:工具之所以能動態產生文件,主要依據我們在開發.NET程式時,所加註的 XML註釋,如:

/// <summary>
///  This class performs an important function.
/// </summary>
public class MyClass{}

在專案中相關的 summary, parameters , type, returns 等說明,開發人員於開發階段,都應該正確輸入,若有遺漏也要記得補上。如此文件產生時,才會更加完善。

提醒:這套工具前置動作較多,但實際運作時相對簡單,加上可指令化,更能方便與 CI Server 整合。

使用方式

1. 安裝 SandcastleSandcastle Help File Builder 工具 (可參閱此篇記錄)

2. 開啟「專案建置時產出XML文件檔案」功能。(VS開啟專案,在專案上點擊滑鼠右鍵 → 屬性 → 建置頁籤 → 勾選 XML文件檔案 → 儲存後,進行編譯)


3. 有了XML之後,再來就是使用工具,試著產生文件看看。

- 建立新文件專案 (設定文件的專案結構、文件型態)


- Documentation Source 滑鼠右鍵 → Add Documentation Source → 找到剛剛的 dll 與 xml,選擇 WebSite 型態的文件。

- Help File:自訂title、輸出程式語言模式 設定。(其他頁籤的設定,可是需求再進行設定) → 儲存後,即可編譯。

- 開始建置文件。(建置成功後,會產生Help資料夾,內有我們選擇的WebSite網站)

- 查看一下產出的文件成果。

4. 指令化。為了方便整合至 CI Server 環境,我們可以透過以下指令來處理。

<# 產生.NET Library文件 #>
 
#Sandcastle Help File Builder 根目錄 (請確認執行路徑)
$SHFB_Root_Path = "/property:SHFBROOT=C:\Program Files (x86)\EWSoftware\Sandcastle Help File Builder"
 
#Sandcastle Help File Builder 專案目錄 (請自行調整路徑)
$SHFB_Project_Path = "D:\DownloadTempR\Document\MyStorage\MyStorage_HelpDoc.shfbproj"
 
#文件站台 (請自行調整路徑)
$Result_WebSite = "D:\DownloadTempR\Document\MyStorage\Help\index.html"
 
#執行 (請確認執行路徑)
C:\Windows\Microsoft.NET\Framework64\v4.0.30319\MSBuild.exe /p:Configuration=Debug $SHFB_Root_Path $SHFB_Project_Path
 
#使用Chrome開啟結果 (請自行調整瀏覽工具)
START Chrome $Result_WebSite


(這裡的警告,是提醒我們,相關註釋沒寫好,記得要去補上)

5. 若想要加 Document 列入版控,可以將其加入類別庫的方案中。
    新建 Document 專案後,Documentation Source 滑鼠右鍵 → Add Documentation Source → 找到需要產出文件的 dll 與 xml。


在 Documentation 專案上 → 滑鼠右鍵 → 屬性 (其他步驟跟上面提到的一樣)

結論

目前除了使用 BDD 開發模式,透過完善需求描述、產生 Production Code 的方式;自然地把 Code、文件同時完成。

還有 WebAPI2 的 Help Page, Swagger,也是為了降低串接 API 的溝通問題而產生的解決方案。

透過以上的作法也能快速的產生類別庫文件,提供給同事來使用。

而上述環繞於「動態產生有效的文件」的這個需求,除了因為我們"懶"的再一字一句的打,更希望更自動化的產出有用文件;把節省下來時間,用來開發更好的服務。

最後當我們在開發階段時,記得順手補上相關 summary, parameters , type, returns 等註釋;除了更清楚自己開發的 API 用途,也有助於後續產生「有效文件」。