Sandcastle入門：建立C#幫助文件

使用Sandcastle

4.1使用平臺

（1）作業系統：
Windows Server 2003; Windows XP Service Pack 2; Windows Vista;

（2）必備軟體：
Microsoft .NET Framework Version 2.0
HTML Help Workshop——如果需要編譯生成CHM文件（需要用到其中的hhc.exe檔案）

（3）可選軟體：
Visual Studio 2005
MS Help Compiler from VS SDK

4.2使用方式（可選介面）Ref[2]

（0）使用Sandcastle原始的命令列方式

（1）Sandcastle Help File Builder
它提供一個類似於NDoc的介面，允許你輸入現有的NDoc專案，自動完成建立過程。

（2）SandcastleGUI
這是一個免費的Sandcastle GUI前端介面。利用它可以在圖形介面操作，省去使用者輸入命令列的麻煩。並且具有以下擴充Ref[6]：
=============================================================================
>>自動在文件中插入MSDN文章連結
>>可以選擇程式集中的某個名稱空間生成文件，而不是預設的整個程式集
>>多種輸出方式：網站、CHM幫助檔案或輸出二者
>>自定義幫助文件頭部（公司LOGO以及產品名稱等）
>>自定義幫助文章頁尾（版權資訊等）
>>在文件中插入自定義的影像
>>文件的程式碼例項中將C#語法高亮顯示
=============================================================================

（3）Sandcastle CHM編譯BAT指令碼和配置實用工具
這是一個配置實用工具和批處理指令碼，由它通過Sandcastle可建立MSDN形式的類文件CHM檔案。

（4）DocProject
DocProject drives the Sandcastle help generation tools using the power of Visual Studio 2005/2008 and MSBuild
生成文件步驟

前提：程式碼文件中使用規範的///註釋，具體規範檢視MSDN-建議的文件註釋標記（C#程式設計指南）。也可以參看本人另一篇介紹文章：《C#中的XML註釋》。

5.0 使用命令列方式

參考文章：Ref[7]
——使用sandcastle自帶的例子test.cs來生成CHM檔案
==========================================================================

1.在命令列下開啟該文件所在的路徑。例如：

cd \Program Files\Sandcastle\Examples\Sandcastle

2.編譯該C#檔案，並從中抽取///註釋：/t引數使得其編譯為dll檔案，/doc引數使得其同時生成包含///註釋的comments.xml文件。

csc /t:library /doc:comments.xml test.cs

3.執行MrefBuilder生成中間檔案reflection.org

MRefBuilder test.dll /out:reflection.org

4.執行XslTransform將上述中間檔案轉換成xml格式（vs2005）（瑤瑤按：使用prototype請參閱Ref[7]原文）

XslTransform. /xsl:"..\..\ProductionTransforms\ApplyVSDocModel.xsl" reflection.org /xsl:"..\..\ProductionTransforms\AddFriendlyFilenames.xsl" /out:reflection.xml

5.生成主題清單

XslTransform. /xsl:..\..\ProductionTransforms\ReflectionToManifest.xsl reflection.xml /out:manifest.xml

6.生成輸出目錄結構（vs2005）

call ..\..\Presentation\vs2005\copyOutput.bat

7.執行BuildAssembler生成HTML主題檔案

BuildAssembler /config:sandcastle.config manifest.xml

8.生成HTML help專案

XslTransform. /xsl:..\..\ProductionTransforms\ReflectionToChmProject.xsl reflection.xml /out:Output\test.hhp

9.生成中間表格內容（vs2005）

XslTransform. /xsl:..\..\ProductionTransforms\createvstoc.xsl reflection.xml /out:toc.xml

10.生成HTML help專案資訊

XslTransform. /xsl:..\..\ProductionTransforms\TocToChmContents.xsl toc.xml /out:Output\test.hhc

XslTransform. /xsl:..\..\ProductionTransforms\ReflectionToChmIndex.xsl reflection.xml /out:Output\test.hhk

11. 執行hhc生成CHM

hhc output\test.hhp

==========================================================================

==========================================================================
Note:7. We are providing VS 2005 transforms under Presentation/VS2005 folder and the transforms shipped with the previous versions under Presentation/Prototype folder.
For building VS2005 format please use sandcastle.config file from C:\Program Files\Sandcastle\Presentation\vs2005\Configuration folder as it uses shared content from C:\Program Files\Sandcastle\Presentation\vs2005\Content and transforms from C:\Program Files\Sandcastle\Presentation\vs2005\Transforms
==========================================================================

5.1 Sandcastle Help File Builder

參考文章：Ref[5]
==========================================================================
1.首先要為專案生成一個包含註釋的XML檔案
在c#專案中滑鼠右鍵點選所選的專案，選擇Properties->Build項，勾選XML documentation file。設定完畢編譯專案，就可以生成屬於它的xml檔案了。
2.開啟我們已經安裝好的Sandcastle Help File Builder並對它進行設定
　　>>點選Add按鈕，選中專案生成的exe,dll,xml檔案
　　>>儲存該專案後點選Namespaces按鈕，選中想要生成幫助文件的Namespace
　　>>設定Dependencies選項，把專案中所引用到的dll檔案載入進去
　　>>設定HtmlHelp1xCompilerPath為HTML Help Workshop的安裝路徑，
　　>>設定SandcastlePath為Sandcastle的安裝路徑
3.點選頂頭選單Documentation下拉選單中的Build Project選項（或直接使用快捷鍵Ctrl+Shift+B）編譯即可生成所需的幫助文件
4.該文件的預設輸出路徑在專案所在目錄的Help資料夾下，當然也可以更改Sandcastle Help File Builder中的設定，自己設定它的輸入路徑。==========================================================================

5.2 SandcastleGUI

以下圖片參考文章：Ref[6]（按：新版本的介面有差異，但大體相同。）
介面：

1）生成各專案的*.dll和*.xml檔案（在vs2005中編譯選項設定，具體前面5.1 Sandcastle Help File Builder的生成步驟中已提及）；
2）將*.dll和*.xml檔案放在一個目錄A下；將所有要附加的圖片（比如類圖和時序圖）放在另一個並行的目錄B下（注意不能有子資料夾）；
3）啟動SandcastleGUI，設定：
Directory that contains assemblies to document項選擇目錄A；
Output directory項選擇一個空資料夾，如C；
Directory to include in documentation項選擇目錄B；
其它如C#語法、是否包含C#例子、生成文件型別（website或chm）等選項根據需要填。
4）設定完成後最好Save settings，因為可能常常要用到。然後Start documenting。
5）等待生成完成後就可以在C目錄下找到chm檔案了：

5.3 Sandcastle CHM編譯BAT指令碼和配置實用工具

未找到相關文章

5.4 DocProject

參考文章：Ref[4]
——使用MSDN上包含有標準註釋的XML文件生成幫助檔案示例
==========================================================================
1 先編寫一個類庫，這裡使用的是MSDN上包含有標準註釋的"XML文件"示例
2 開啟下載到的工程檔案, 開啟XMLsample.cs, 可以看到各種註釋的詳細解釋

3.使用DocProject方式, 在確保安裝了DocProject後, 為工程新增新專案

==> ==> ==> ==>

4.編譯DocProject前, 務必使你所要生成文件的類庫編譯輸出註釋的XML檔案, 詳細方法請檢視在Visual Studio中生成“XML文件”示例
5.編譯DocProject專案, 等待十幾分鍾(似乎有點慢, 即使類庫很小), 就會在該專案下看到HTML版和CHM版的文件了。

來自 “ ITPUB部落格 ” ，連結：http://blog.itpub.net/12639172/viewspace-364712/，如需轉載，請註明出處，否則將追究法律責任。