使用 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++ 三種語法,看起來真是挺專業地呀 ^_^

9 則留言:

  1. 大大
    可以問一下如果想把產出的文件給嵌入到MSDN的話該如何做呢?!
    看市面是有的元件裝完會自己把他們的說明給嵌到MSDN,如此只要按F1就可以查詢他們原件的用法

    回覆刪除
  2. Hi nung,
    你有試過 HelpProvider 嗎?
    http://msdn.microsoft.com/zh-tw/library/system.windows.forms.helpprovider(VS.80).aspx

    可以參考看看這篇:
    http://www.codeproject.com/KB/dotnet/HelpIntegrationInDotNet.aspx

    或者這篇的作法:
    http://www.codeproject.com/KB/cs/ContextHelpMadeEasy.aspx

    回覆刪除
  3. thx
    我沒試過
    謝謝提供資訊
    我會試試看的

    回覆刪除
  4. 請問~
    要如何下 namespace 的註解呢??

    回覆刪除
  5. Hi Jaba,
    如果是 C#,在你的類別宣告上方或 method、屬性上方輸入 '///' (不含單引號),Visual Studio 就會產生 XML 註解的 "骨架" 讓你填 "肉" 了。例如:

    /// 在這行敲三個斜線你就知道怎麼做了
    public class MyClass
    {
    /// 在這行敲三個斜線就知道怎麼做了
    public MyMethod(int aa, string bb)
    }

    如果是 VB,則是三個連續單引號:'''

    回覆刪除
  6. 您好
    如果要在有斷行的功能的話
    列如 功能說明 或者 ReMarks要用到斷行
    請問要怎樣輸入 謝謝

    回覆刪除
  7. XML 註解的內容,可以用 HTML 標籤喔。所以您要斷行的話,可以用<BR />,或者其他有分段作用的 HTML 標籤。

    回覆刪除
  8. 您好 謝謝您
    我已經找到方法了
    文字< br >< /br > || < br >文字< /br >
    謝謝

    回覆刪除
  9. 版主的方式比較方便
    謝謝您

    回覆刪除

技術提供:Blogger.
回頂端⬆️