Sandcastle幫助文件生成器使用介紹

一、軟體介紹

sandcastle是乙個管理類庫的文件編譯器，是用於編譯發布元件（assembly）資訊的乙個工具，這個工具通過反射和xslt技術，可以從dll檔案及其xml注釋（命令列編譯時加/doc引數或vs2005設定專案屬性得到）得到乙個完整的幫助文件，格式可以是html或chm甚至是任何自定義的格式。

sandcastle與.net framework 2.0和.net compact framework組合使用。sandcastle支援本地化，並提供乙個基本的命令列編譯器介面和乙個visual studio外掛程式。

sandcastle中共有三個元件：mrefbuilder、build assembler和xsltransform。這些工具使用編譯彙編**時生成的輸出結果，包括dll檔案以及xml注釋檔案。

mrefbuilder反射乙個專案的彙編**並生成乙個輸出檔案。mrefbuilder是乙個隨sandcastle安裝的命令列工具。它生成的輸出檔案通過xsltransform命令列工具轉換成乙個叫做reflection.xml的檔案。reflection.xml檔案包含所有文件資料，但不提供顯示細節。

mrefbuilder完成工作後，立即由build assembler接手處理。build assembler可由命令列工具buildassembler啟動。它利用由mrefbuilder生成的資料(reflection.xml)和任何**注釋（儲存在獨立的xml檔案中），生成按邏輯分組的html檔案。html help compiler再利用這些html檔案生成最終結果。

該工具並未限制你一次處理乙個彙編。如果你需要處理幾個彙編**，你必須深入了解sandcastle配置檔案。它是乙個包含建立幫助檔案主題所需步驟的xml檔案。

sandcastle生成的輸出結果具有以下特點：

ø 類似於msdn布局的介面。

ø 自動生成索引項、內容專案表、主題塊和頁面布局，提高一致性和熟悉程度。

ø 自動生成語法宣稱部分。

ø 自動生成繼承表。

ø **彩色化。

ø 提供多種風格和語言選擇，終端使用者可從中選擇自己最喜歡的形式。

ø 輸出結果以html和css形式顯示，微軟承諾將來提供更多選擇。

二、軟體使用

軟體的使用方式大致有以下5種：

（1）使用sandcastle原始的命令列方式

（2）sandcastle help file builder

（3）sandcastlegui

（4）sandcastle chm編譯bat指令碼和配置實用工具

（5）docproject

文章以第（2）種為例，介紹sandcastle的使用

1、關於生成文件**注釋的規範：

在源**檔案中，具有規範格式的注釋可用於指導工具sandcastle.msi根據這些注釋和它們後面的源**元素生成 xml。使用這類語法的注釋稱為文件注釋 (documentation comment)。這些注釋後面必須緊跟使用者定義型別（如類、委託或介面）或者成員（如欄位、事件、屬性或方法）。xml 生成工具稱作文件生成器 (documentation generator)。由文件生成器產生的輸出稱為文件檔案 (documentation file)。文件檔案可作為文件檢視器 (documentation viewer) 的輸入；文件檢視器sandcastle是用於生成型別資訊及其關聯文件的某種視覺化顯示的工具。

新的**注釋規範需要使用以三個斜槓 (///) 開始注釋，這些注釋後面必須緊跟它們所注釋的使用者定義型別（如類、委託或介面）或者成員（如欄位、事件、屬性或方法）.對注釋解說需要使用有效的xml標記。

部分標記如下:

--- sandcastle //原始

--- shfb(sandcastle help file builder) //文章我們要用到的。

①如果之前安裝過其它版本，請先解除安裝後再裝。

開啟sandcastleinstaller.exe進入安裝介面

安裝完成後，便可以在開始選單中找到，開啟程式，如下

a.開啟軟體後首先新建解決方案，注意不要建在桌面等位置，否則生成時會報錯。

b.解決方案建成後，在project explorer 中右擊 documentation sources 上右擊新增需要生成幫助文件的dll檔案。圖中①處為我新增的需要生成幫助文件的dll檔案

c.底下content layout1.content為生成的幫助文件的樣式，完全可以不要。

d.選擇要生成幫助文件的格式，如圖中②處，我要生成html格式的幫助文件。

e.其它設定預設即可，過會底下會做介紹。

f.點選③處開始生成，如圖

build completed successfully at 09-09-2013 11:47 下午. total time: 00:01:11.3906

即可在sandcastle解決方案目錄下看到help資料夾，即是生成的幫助檔案。

h.如果不能編譯生成chm文件或者生成chm時報錯，則需要安裝html help workshop（需要用到其中的hhc.exe檔案）

3、整合到visual studio中

a.回到sandcastle安裝程式目錄，開啟 installresources資料夾,看到以下三個檔案

雙擊最下邊的vsix檔案，反應一會兒會彈出如下錯誤，即表示安裝成功了：

b.現在在解決方案中新增專案，如下

c.選擇documentation-->sandcastle help file builder project-->確定

d.雙擊project properties 可以設定專案的屬性

屬性個性化定製主要屬性有：

1.生成屬性設定，如需要生成什麼型別的文件（可選chm、**站點等）

2.文件內容屬性設定，如對命名空間的解說。（命名空間在c#**中是不可以有注釋的，故在此可以設定，也可以在專案中新建乙個類namespacedoc.cs其**為：

1
namespace
testforhelp
29   }

3.文件檔案的屬性設定:如頁首、頁尾、版權資訊。

e.同樣，右擊 documentation sources 上右擊新增需要生成幫助文件的dll檔案，可一次新增多個

f.在專案名上（如documentationhelp）右擊，新增--新建項，可指定專案模板

g.所有設定完成後，生成專案，即可得到想要的幫助文件，同樣儲存在專案下help資料夾下。

h.再次提醒，如果不能編譯生成chm文件或者生成chm時報錯，則需要安裝html help workshop（需要用到其中的hhc.exe檔案）

Sandcastle幫助文件生成器使用介紹

Sandcastle生成幫助文件

簡單的使用SandCastle建立C 幫助文件

文件API生成神器SandCastle使用心得

Sandcastle幫助文件生成器使用介紹

Sandcastle生成幫助文件

簡單的使用SandCastle建立C 幫助文件

文件API生成神器SandCastle使用心得

相關推薦