有些場合需要提供Lib 或元件的說明文件，雖然我覺得引用 Lib 並且同時有輸出的 .xml 檔，這樣在寫
程式的時候有相對應的輸入提示也就足夠了，畢竟隨著時光推移註解有時候還會失準(誤)，依據情境
找了對應的套件，Sandcastle Help File Builder(SHFB)，紀錄實際操作...
如何安裝
找到這套Sandcastle Help File Builder(SHFB)，目前版本是 v2023.7.8.0 ，最後更新時間大概落在七月，
有官方的說明文件，看起來似乎也是用自身的工具產生的，以下來說明安裝步驟
來到 release 頁面，下方會有安裝檔(installer)跟相關原始碼可以下載
下載安裝檔後解壓縮
點選 .exe 檔案開始安裝
安裝過程大部分是「Next」，亦可隨時 「Previous」
來到 Sandcastle Help Fle Builder and Tools 步驟時，中間下方有個 「Install SHFB」 按鈕
點擊後會彈出另外的視窗
勾選同意，然後下一步
使用預設路徑安裝即可
點選 Install
等待完成安裝
安裝完成
再回到Sandcastle Guided Installation 的安裝視窗，繼續往下個步驟安裝
來到 SHFB Visual Studio Package 的步驟
這邊說明安裝 VS 套件，並且預設作用於目前系統中的 Visual Studio Community 2022 版本，
點選 「Install Package」 按鈕
等待初始化後安裝
完成安裝後，再前往下個步驟
來到 MAML Snippet Files 步驟，請點選 「Install Snippets」
安裝完成後，緊接著持續往下個步驟，一路可以到 Completion
檢視安裝成果
搜尋工具列 Sandcastle 應該會找到 GUI 項目
開啟 VS2022，建立新專案，搜尋選項會有 Documentation
Documentation Project 使用
接著來說明 Documentation 專案如何使用
在方案中新增 Documentation 專案，以下為預設內容
加入要產生文件的專案
以上點選後，選擇要加入的專案檔(.csproj
成功加入後，會在 Documentation Sources 目錄下產生Link
設定輸出文件檔案
在要育產生文件的專案上點選滑鼠右鍵，點選「屬性」> 建置 > 輸出 / 文件檔案
Documentation Project 設定
上一段加入了要產生文件的專案，接下來針對文件專案有哪些項目可以設定
叫出屬性視窗
預設編輯畫面如下
可切換 Framework version，預設是 4.7.2，亦有 .net core
可以選擇文件支援哪些程式語言，預設會有以下4種勾選
切換 presentation style，預設為Default 2022
若調整為 VS2013，則有HTML Help1 (chm) 、 Website (HTML/ASP.NET)、MS Help Viewer (mshc) 等類型
首選HTML Help1 (chm) 、 Website (HTML/ASP.NET)兩種格式，須注意若勾選 MS Help Viewer (mshc)
檔案名稱不能有 「.」、「&」、「#」，該項目為 離線文件
來到 Help File 項目
這邊可以調整檔案名稱
來到 Visibility 選項
這邊是勾選哪些文件內容要被輸出，如 internal member 或是 inherited base class members
一般有許可以忽略inherited .net framework members、inherited base class members，
並且開啟 internal members、protected member of sealed classes
組件版號設定
針對組件版號，可以在 AsseblyInfo.cs 檔中檢視
Lib 專案
開啟方案總管的屬性，在套件 \ 一般 頁籤
組件版本沒有輸入就會是 1.0.0.0，這邊測試輸入 1.0.0.12345
產品版本
文件的版號設定
先調整 welcom 內容
可以透過 「ContentLayout.content 」來管理，點選 ContentLayout.content
說明 ContentLayout.content 設定
建置專案並開啟檔案.chm
檔案目錄預設會放在 Help 資料夾下
Documentation\Help
Link Text 會連結到 Version History
此時修改文字
若沒有填就會預設帶入文字
新增版號子版號
新增完成後
編輯內容，須將較新的版本往上提升
其中 Link tag 的 href 屬性，內容為 VersonHistory 的ID
若要在內文加上圖片
使用 <mediaLink>M<image xlink:href="123" /></mediaLink>，其中 裡面只能有一個 image 標籤
href 內容需要 檔案的 ID 不是檔名
檔案放置
可以檢視圖檔屬性(F4)
將說明文件架站
此時輸出會需要有 Website 類型的輸出，如下圖
開啟 IIS 管理員
Default Web Site 滑鼠右鍵「新增應用程式」
將實體目錄指到 Help 資料夾即可
檢視應用程式
結果呈現，其中 WebSite 的好處是，有支援搜尋內文的功能
解決命名空間紅字
有時候文件會有紅字，如下圖
此時需要設定 namespace summaries(參考)
接著會列出相關組件資訊，並且一一設定 namespace 即可修除
透過 GUI 工具直接編輯 Documentation Project
前面我們有提到，若是成功安裝了Sandcastle 工具，工具列會有個 GUI 的項目，方便你快速編輯專案
開啟工具後，將既有的文件專案開啟
找到你的文件專案(.shfbproj)
開啟後就會出現類似的編輯內容
以上打好收工
【參考】
沒有留言:
張貼留言