使用 Sandcastle Help File Builder 製作類別庫文件

簡介

CodePlex 網站上有一個 Sandcastle 專案,這是用來製作類別庫文件的工具,如果你在撰寫 .NET 程式時,有輸入 XML 註解,這個工具可以幫你抓出來,並產生類似 MSDN help 那樣的說明文件(你的專案的 Build 選項中的 Output > XML documentation file 選項必須勾選)。

可是 Sandcastle 是個命令列工具,它沒有 GUI,所以用起來不是那麼方便。這裡要介紹的就是搭配 Sandcastle 的一套 GUI 工具:Sandcastle Help File Builder

Sandcastle 能夠產生的說明文件格式包括:
  • HtmlHelp 1.x(.CHM)
  • HtmlHelp 2.x(.HxS)
  • 網頁格式(.html)
你需要安裝的東西有:
要特別注意的是,Visual Studio SDK 裡面也有附 Sandcastle,但是版本比較舊。你必須在安裝完上述軟體後,檢查系統的環境變數:
  1. 查看「使用者變數」,若 PATH 裡面有 Sandcastle,就把它刪掉。
  2. 查看「系統變數」,確認 DXROOT 變數是指向 "C:\Program Files\Sandcastle\"(這是 Sandcastle 的預設安裝路徑)。

使用

安裝程序稍嫌繁瑣,使用起來倒很簡單。首先,從程式集點選 Sandcastle Help File Builder > Sandcastle Help File Builder GUI(以下簡稱 SHFB),進入 SHFB 之後,點 File > New Project,然後在 Project Explorer 視窗裡面展開專案節點,在 Documentation Sources 上點右鍵,選 Add Documentation Source,就可以將你要產生說明文件的 .NET 組件加進專案。

你會需要設定一些專案屬性,像是:輸出的文件類型(.CHM、.HxS、還是網頁,可複選)。從主選單點 Window > Project properties 或按 F4 即可開啟專案屬性設定視窗。參考下圖:



圖中的 HelpFileFormat 就是輸出的文件格式。除此之外,通常至少還要修改以下屬性:
  • HtmlFileName - 檔案名稱,預設是 Document。
  • HelpTitle - 說明文件的視窗標題。
都設定好之後,點擊主選單的 Document > Build Project 就可以產生說明文件了。很簡單吧?!

產生的檔案是放在專案屬性 OutputPath 所指定的目錄下,這裡貼兩張由此工具產生出來的 HtmlHelp 1.x(.CHM)說明文件的畫面:





語法的部分還分別列出 C#、Visual Basic、和 Visual C++ 三種語法,看起來真是挺專業地呀 ^_^

Post Comments

技術提供:Blogger.