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

轉自：http://www.cnblogs.com/net515/p/3311584.html

1、軟件介紹

      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形式顯示，微軟承諾未來提供更多選擇。

2、軟件使用

  軟件的使用方式大體有如下5種：

（1）使用Sandcastle原始的命令行方式

（2）Sandcastle Help File Builder

（3）SandcastleGUI

（4）Sandcastle CHM編譯BAT腳本和配置實用工具

（5）DocProject 

 文章以第（2）種爲例，介紹Sandcastle的使用

   一、關於生成文檔代碼註釋的規範：

　　在源代碼文件中，具備規範格式的註釋可用於指導工具Sandcastle.msi根據這些註釋和它們後面的源代碼元素生成 XML。使用這類語法的註釋稱爲文檔註釋 (documentation comment)。這些註釋後面必須緊跟用戶定義類型（如類、委託或接口）或者成員（如字段、事件、屬性或方法）。XML 生成工具稱做文檔生成器 (documentation generator)。由文檔生成器產生的輸出稱爲文檔文件 (documentation file)。文檔文件可做爲文檔查看器 (documentation viewer) 的輸入；文檔查看器Sandcastle是用於生成類型信息及其關聯文檔的某種可視化顯示的工具。

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

部分標記以下: 

   

二、下載並安裝

  --- Sandcastle    http://sandcastle.codeplex.com/   //原始

  --- SHFB(Sandcastle Help File Builder)   http://shfb.codeplex.com/  //文章咱們要用到的。

 ①若是以前安裝過其它版本，請先卸載後再裝。

 ②下載完成後解壓，我使用的爲SHFBGuidedInstaller_1970版本，獲得以下

  

 

打開SandcastleInstaller.exe進入安裝界面

 

 

安裝至關簡單，在連網的環境下，須要的組件會自動提示下載安裝。測試時，除了MAML Schema IntelliSense 及MAML Snippet Files選擇了跳過沒有安裝之外，其它全根據提示安裝上了。（由於不明白那兩個東西是作什麼的）。

 

安裝完成後，即可以在開始菜單中找到，打開程序，以下

 

 

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

b.解決方案建成後，在Project Explorer 中右擊 Documentation Sources 上右擊添加須要生成幫助文檔的dll文件。圖中①處爲我添加的須要生成幫助文檔的dll文件

c.底下Content Layout1.content爲生成的幫助文檔的樣式，徹底能夠不要。

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

e.其它設置默認便可，過會底下會作介紹。

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

 

g.生成完成後，會看到提示：

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文件）

 

三、集成到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
2   {
3     ///<summary>
4    ///These are the namespace comments for New <c>TestForHelp</c>
5    ///</summary>
6    [System.Runtime.CompilerServices.CompilerGeneratedAttribute()]
7       classNamespaceDoc
8        {  }
9   }

 

   3.文檔文件的屬性設置:如頁眉、頁腳、版權信息。

e.一樣，右擊 Documentation Sources 上右擊添加須要生成幫助文檔的dll文件，可一次添加多個

f.在項目名上（如DocumentationHelp）右擊，添加--新建項，可指定項目模板

 

g.全部設置完成後，生成項目，便可獲得想要的幫助文檔，一樣保存在項目下Help文件夾下。

h.再次提醒，若是不能編譯生成CHM文檔或者生成CHM時報錯，則須要安裝HTML Help Workshop（須要用到其中的hhc.exe文件）

 參考資料：

 1. 使用Sandcastle幫助文檔生成流程

 2. 利用SandCastle生成幫助文檔

 3. 使用 Sandcastle 生成 chm 幫助文檔 (使用Sandcastle原始的命令行方式)

 4.軟件的幫助文檔，講得很全，但全是英文。