Sandcastle 學(xué)習(xí)教程 （1） 基礎(chǔ)入門

目前可找到SandCastle學(xué)習(xí)資源十分有限。而據(jù)我所知能夠生成幫助文檔的工具目前只有SandCastle（NDoc早就已經(jīng)停止更新了，參見“相關(guān)文檔”中的第二篇。） 有關(guān)XML注釋，我曾經(jīng)寫過兩篇文章，里面也簡單介紹了如何使用SandCastle,本系列教程希望能夠深入的研究SandCastle，比如SandCastle的各個組件，高級的使用技巧，如何與持續(xù)構(gòu)造（FinalBuilder）繼承等。本篇文檔翻譯自SandCastle的兩篇官方文檔。目前官方文檔只能找到下面翻譯的內(nèi)容。

概要

目前可找到SandCastle學(xué)習(xí)資源十分有限。而據(jù)我所知能夠生成幫助文檔的工具目前只有SandCastle（NDoc早就已經(jīng)停止更新了，參見“相關(guān)文檔”中的第二篇。）

有關(guān)XML注釋，我曾經(jīng)寫過兩篇文章，里面也簡單介紹了如何使用SandCastle：

• 使用.NET中的XML注釋(一) -- XML注釋標(biāo)簽講解
• 使用.NET中的XML注釋(二) -- 創(chuàng)建幫助文檔入門篇

 

本系列教程希望能夠深入的研究SandCastle，比如SandCastle的各個組件，高級的使用技巧，如何與持續(xù)構(gòu)造（FinalBuilder）繼承等。

本篇文檔翻譯自SandCastle的兩篇官方文檔。目前官方文檔只能找到下面翻譯的內(nèi)容。

一.SandCastle介紹

Sandcastle是托管類庫的文檔編譯器，用來生成微軟風(fēng)格的API接口說明和程序結(jié)構(gòu)說明的幫助文檔。通過反射關(guān)聯(lián)的.NET Framework 程序集，使用源代碼中的 XML文檔注釋（在C#中的“///”或者VB中的“’”）生成API接口說明文檔。通過反射dll文件創(chuàng)建程序結(jié)構(gòu)說明，其他的比如提醒和參數(shù)等信息都是通過源代碼中的XML注釋導(dǎo)出的。

生成的文檔如下圖所示：

二. SandCastle特性

SandCastle是由微軟提供的用于生成.Net幫助文檔的工具，可以生成API接口說明和程序結(jié)構(gòu)說明。

• 支持.NET Framework 2.0
• 使用VersionBuilder工具支持不同版本的項目
• 使用CHMBuilder 工具用來生成HTML 1.x版本的chm文件。
• 符合 Visual Studio 2008 的幫助主題
• 使用Windows的PowerShell腳本生成文檔接口說明
• 支持5星MSDN風(fēng)格的投票反饋

 

三. 系統(tǒng)要求

操作系統(tǒng)

• Windows Server 2003;
• Windows Vista;
• Windows XP Service Pack 2

軟件環(huán)境

• .NET Framework 2.0， 可以在.NET Framework網(wǎng)站下載。
• HTML Help Workshop，支持HTML 1.x 文件，可以通過 HTML Help 下載站點下載，或者通過Visual Studio SDK 安裝。

推薦環(huán)境

• MS Help 2.0 Compiler，支持HTML 2.0 文件，是VS2005或更新的版本安裝時的一部分，可以支持生成HTML 2.0（.Hxs）文件。
• Visual Studio 2005，可以與幫助文檔集成。

四. 安裝SandCastle

• 確定機(jī)器上已經(jīng)安裝了HTML Help Workshop，創(chuàng)建Help 2.0(HxS)文件還需要Help 2.0 Compiler。Visual Studio 2008 SDK已經(jīng)包括了這兩部分。
• 卸載早期的SandCastle版本（不是隨著Visual Studio 2008 SDK安裝的）。
• 從CodePlex下載 SandCastle Installer， 并運(yùn)行安裝程序。

注意：

如果想要安裝Visual Studio 2008 SDK，請在安裝SandCastle之前安裝。這是因為Visual Studio 2008 SDK 安裝時更新了PATH和DXROOT兩個系統(tǒng)注冊的變量。如果在SandCastle安裝后這兩個變量被更新，將導(dǎo)致SandCastle無法工作。如果已經(jīng)安裝了SandCastle，有下面兩個方法：

• 安裝Visual Studio 2008 SDK后，卸載SandCastle，重新安裝SandCastle。
• 重新設(shè)置PATH和DXROOT兩個環(huán)境變量

如果是非x86（32位機(jī)器）機(jī)器，請參考下文。

在AMD64機(jī)器上設(shè)置SandCastle

• 在開始菜單上，在“我的電腦”上單擊鼠標(biāo)右鍵，選擇“屬性”。
• 在左側(cè)的區(qū)域中，單擊“高級系統(tǒng)設(shè)置”。
• 在“高級”標(biāo)簽中單擊“環(huán)境變量”按鈕。
• 在“環(huán)境變量”中找到“PATH”，單擊“編輯”。
• 將下面的變量添加到屬性值中：
  %ProgramFiles(x86)%\HTML Help Workshop;%ProgramFiles(x86)%\Common Files\Microsoft Shared\Help 2.0 Compiler