Nick's Blog
0%

使用 SHFB 自動化建立 Assembly 的 Help 文件

發表於 更新於 分類於 閱讀次數： Valine：
文章字數： 2.3k 所需閱讀時間 ≈ 4 分鐘

背景

問題描述

專案開發時，PG最不喜歡的無非是：

  1. 寫文件
  2. 對方沒寫文件

心裡OS：「寫Code都來不及，還要維護文件」，然後….文件就這樣爛了….

因為以上種種問題，Live Document 需求就由然而生

如果可以「依據實際的 Code與註解，動態產生文件」…不是很美好嗎？？

接下來就來說明如何實作。

如何開始

安裝

Step 1 - 下載 SHFB

https://github.com/EWSoftware/SHFB/releases

下載 SHFB

Step 2 - 安裝主程式

雙擊安裝程式→Next→Install SHFB


Step 3 - 安裝 Visual Studio 插件重點

Step 4 - 安裝 Visual Studio Schemas(可選的)

Step 5 - 安裝 Visual Studio Snippets(可選的)

Step 6 - 完成安裝

設定

Step 1 - 啟用「建置時產出XML文件檔案」

專案上點擊滑鼠右鍵 → 屬性 → 建置頁籤 → 勾選 XML文件檔案 → 儲存後，進行編譯

:::info
什麼是XML文件檔案？

主要是編輯的時候，根據我們在開發程式時所加上的XML註釋，動態產生的文檔。
:::

例如：

1
2
3
4
5
6
7
8
9
10
11
/// <summary>
/// 這是一個範例方法
/// </summary>
/// <param name="param">輸入的參數</param>
/// <returns>回傳的結果</returns>
public Result MyMethod(Input param)
{
    //do soming..

    return new Result();
}

Step 2 - 新建 Document 專案

方案上點擊滑鼠右鍵 → 加入 → 新增專案

選取「Documemtsation」 → 指定專案名稱 → 確定

Step 3 - 加入需要產出文件的 dll、 xml

Documentation Source 滑鼠右鍵 → Add Documentation Source → 找到需要產出文件的 dll 與 xml

Step 4 - Documemtsation 專案配置

Documemtsation專案 滑鼠右鍵 → 屬性

Step 4-1 配置「Build」頁籤
  1. 左邊頁籤選擇「Build」
  2. PresentationStyle ：選擇VS2013
  3. Build These help file formats(輸出文件格式)：Website(HTML/ASP.NET)
  4. Syntax：輸出程式語言格式

Step 4-2 配置「Help File」頁籤
  1. 左邊頁籤選擇「Help File」
  2. Help title：自訂 title
  3. Help File Language：文件語言(有中文)

其他頁籤的設定，可依需求再進行設定 → 儲存後，即可編譯。

產生說明文件

建置成功 → Documemtsation專案 底下會產生「Help」資料夾 → 裡面有產生的說明文件

產生 「Word」格式說明文件

Documemtsation專案 滑鼠右鍵 → 屬性

  1. 左邊頁籤選擇「Build」
  2. PresentationStyle ：選擇Open XML Document
  3. Build These help file formats(輸出文件格式)：Open XML(docx)

儲存後，編譯，Help資料夾即生成 Word Help 文件。

指令 - 方便整合 CI/CD

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
#Powershell SHFB 自動建置佈暑 HELP 文件指令

#Sandcastle Help File Builder 根目錄 (請確認執行路徑)
$SHFB_Path = "/property:SHFBROOT=C:\Program Files (x86)\EWSoftware\Sandcastle Help File Builder"
 
#Sandcastle Help File Builder Documemtsation 專案目錄 (請自行調整路徑)
$SHFB_ProjectPath = "C:\Nick\Gitlab\GameServer\Indica\Indica.Help.Doc\Indica.Help.Doc.shfbproj"
 
#文件站台 (請自行調整路徑)
$Result_WebSite = "C:\Nick\Gitlab\GameServer\Indica\Indica.Help.Doc\Help\index.html"
 
#Compiler
C:\Windows\Microsoft.NET\Framework64\v4.0.30319\MSBuild.exe /p:Configuration=Debug $SHFB_Path $SHFB_ProjectPath

#使用Chrome 查看文件(自行調整相關工具)
START Chrome $Result_WebSite


:::success
這邊的警告是告訴我們相關XML注解沒有填寫。
:::

結論

  • 養成 XML注解 習慣
  • 產文件可以很優雅
  • 不需要維護文件
  • 整合 CI/CD
  • 如果想制作 WebApi2，更加適合的套件

Ref

Sandcastle Help File Builder 安裝紀錄
使用 Sandcastle Help File Builder 建立 Assembly 的補助說明檔案
使用 Sandcastle Help File Builder 製作類別庫文件
使用 Sandcastle工具在Visual Studio環境產生Help文件

tags: 說明文件 SHFB