使用 Sandcastle Help File Builder 建立 Assembly 的補助說明檔案

相信這不是新的主題了,許多資深的開發人員應該都知道 NDoc 這套產品,只要再專案內容的屬性的建置的選項中,勾選 XML 文件檔案,並在程式碼中使用標準XML註解說明,那麼它可以幫您產生標準的 .chm 的 HELP 說明格式檔案,只不過後來 NDoc 不維護了,所以現在使用免費的軟體來製作專業的 .chm 說明檔,目前免費中比較 Power 的工具算是 Sandcastle Help File Builder 了。

相信這不是新的主題了,許多資深的開發人員應該都知道 NDoc 這套產品,只要再專案內容的屬性的建置的選項中,勾選 XML 文件檔案,並在程式碼中使用標準XML註解說明,那麼它可以幫您產生標準的 .chm 的 HELP 說明格式檔案,只不過後來 NDoc 不維護了,所以現在使用免費的軟體來製作專業的 .chm 說明檔,目前免費中比較 Power 的工具算是 Sandcastle Help File Builder 了。

在開始進行之前,有一些準備工作要完成,當然,您可以先下載 Sandcastle Help File Builder ,它有前導程式會告訴你如果要編譯 .chm 檔,還需要下載安裝哪一些工具。而如果您只是要編譯 .chm 格式的 HELP 說明檔案,只要您有安裝  HTML Help Workshop ,系統就有 .chm 的編譯器,一般正常的來說,只要您有安裝 Visual Studio ,系統就會有安裝 SDK 等相關工具,就會包括 HTML Help Workshop ,您並不需要另外下載來安裝。

 


安裝步驟

1. 下載 Sandcastle Help File Builder

可到下連結下載:

https://shfb.codeplex.com/

image


2. 使用 Sandcastle Help File Builder 前導工具檢察系統是否具備相關的SDK工具

執行 SandcastleInstaller.exe 會看見如下歡迎畫面

image

它需要 .NET Framework 4.0

image

當系統有安裝 HTML Help Workshop 就會顯示

image

若需要編譯 Microsoft Help 2 Compiler 檔案, Sandcastle Help File Builder 會提示可到哪下載安裝 Visual Studio 2008 SDK. Version 1.1,安裝後再使用 Search Again 按鈕來確認是否安裝完成 Visual Studio 2008 SDK. Version 1.1。

image

 


說明:

副檔名為 .chm 是 Microsoft Help 1 格式的說明檔, Microsoft Help 2 Compiler 是從 Visual Studio 2005 開始推出的新版格式,附檔名為 .HxS ,若要使用 Microsoft Help 2 Compiler 建議安裝 Visual Studio 2008 SDK. Version 1.1 內提供的版本。


如果下載安裝 Visual Studio 2008 SDK. Version 1.1 後,可點選執行 VsSDK_sfx.exe

image

完成安裝後,可再點選 Search Again 確認是否安裝完成。


注意:

若要安裝 Visual Studio 2008 SDK. Version 1.1,您的系統必須要有 Visual Studio 2008 的開發工具,否則無法安裝成功。


若您選擇不安裝,系統會出現提示訊息,但不影響後面步驟的進行。

image

當前面的步驟都完成後,接著就是實際安裝 Sandcastle Help File Builder 主要的工具了,您可以點選下方的 Install SHFB 進行安裝。

image

或者也可以在解壓縮的 InstallResources 資料夾內執行 SandcastleHelpFileBuilder.msi。

安裝完成後,也可選擇是否安裝  Sandcastle Help File Builder Visual Studio Package ,它是個 for Visual Studio 的範本,支援 Visual Studio 2010/2012/2013 版本。

接著是在 Visual Studio 安裝編輯 MAML Schema 的 IntelliSense,它會自動偵測您的系統中有安裝的 Visual Studio 版本,如下:

image

然後是安裝 MAML Snippets for Visual Studio,支援 Visual Studio 2008/2010/2012/2013 版本。

image

最後您可以選擇是否安裝選擇性工具 Visual Studio Spell Checker。

要建立 .chm 說明檔案,就如同筆者前面所說的,只要再專案內容的屬性的建置的選項中,勾選 XML 文件檔案,並在程式碼中使用標準XML註解說明,那麼它可以幫您產生標準的 .chm 的 HELP 說明格式檔案。


A. 設定 XML 完件檔案

作法如下圖所示:

image

完成後記得重新編譯。


B.  開啟 Sandcastle Help File Builder 並建立新的專案,再參考剛剛編譯出來的 DLL (Assembly)

image

其中,左邊的 Project Explorer 中的 Documentment Source 是來源的 XML 檔案與 Assembly,References 指的是您要編譯 CHM 的 Assembly 所參考使用到的外部元件 DLL。


C. 設定說明檔顯示的樣板與提供那些語言

image


D. 完成設定後再點選選單的 Documentation –> Build Project 隨即開始編譯 CHM 說明檔案。過程中畫面會顯示編譯過程的 LOG 資訊。

image

最後,我們成功完成的 CHM 說明檔案如下:

image

 

結語

透過這樣的工具,不僅是讓我們的文件更一致化、標準化,也可幫助我們將所開發的元件,快速的產生補助說明檔案提供給元件的使用者參考。


 

簽名:

學習是一趟奇妙的旅程

這當中,有辛苦、有心酸、也有成果。有時也會有瓶頸。要能夠繼續勇往直前就必須保有一顆最熱誠的心。

軟體開發之路(FB 社團)https://www.facebook.com/groups/361804473860062/

Gelis 程式設計訓練營(粉絲團)https://www.facebook.com/gelis.dev.learning/


 

如果文章對您有用,幫我點一下讚,或是點一下『我要推薦,這會讓我更有動力的為各位讀者撰寫下一篇文章。

非常謝謝各位的支持與愛護,小弟在此位各位說聲謝謝!!! ^_^