Sandcastle 学习教程 （1） 基础入门

概要

目前可找到SandCastle学习资源十分有限。而据我所知能够生成帮助文档的工具目前只有SandCastle（NDoc早就已经停止更新了，参见“相关文档”中的第二篇。）

有关XML注释，我曾经写过两篇文章，里面也简单介绍了如何使用SandCastle：

• 使用.NET中的XML注释(一) -- XML注释标签讲解
• 使用.NET中的XML注释(二) -- 创建帮助文档入门篇

 

本系列教程希望能够深入的研究SandCastle，比如SandCastle的各个组件，高级的使用技巧，如何与持续构造（FinalBuilder）继承等。

本篇文档翻译自SandCastle的两篇官方文档。目前官方文档只能找到下面翻译的内容。

一.SandCastle介绍

Sandcastle是托管类库的文档编译器，用来生成微软风格的API接口说明和程序结构说明的帮助文档。通过反射关联的.NET Framework 程序集，使用源代码中的 XML文档注释（在C#中的“///”或者VB中的“’”）生成API接口说明文档。通过反射dll文件创建程序结构说明，其他的比如提醒和参数等信息都是通过源代码中的XML注释导出的。

生成的文档如下图所示：

二. SandCastle特性

SandCastle是由微软提供的用于生成.Net帮助文档的工具，可以生成API接口说明和程序结构说明。

• 支持.NET Framework 2.0
• 使用VersionBuilder工具支持不同版本的项目
• 使用CHMBuilder 工具用来生成HTML 1.x版本的chm文件。
• 符合 Visual Studio 2008 的帮助主题
• 使用Windows的PowerShell脚本生成文档接口说明
• 支持5星MSDN风格的投票反馈

 

三. 系统要求

操作系统

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

软件环境

• .NET Framework 2.0， 可以在.NET Framework网站下载。
• HTML Help Workshop，支持HTML 1.x 文件，可以通过 HTML Help 下载站点下载，或者通过Visual Studio SDK 安装。

推荐环境

• MS Help 2.0 Compiler，支持HTML 2.0 文件，是VS2005或更新的版本安装时的一部分，可以支持生成HTML 2.0（.Hxs）文件。
• Visual Studio 2005，可以与帮助文档集成。

四. 安装SandCastle

• 确定机器上已经安装了HTML Help Workshop，创建Help 2.0(HxS)文件还需要Help 2.0 Compiler。Visual Studio 2008 SDK已经包括了这两部分。
• 卸载早期的SandCastle版本（不是随着Visual Studio 2008 SDK安装的）。
• 从CodePlex下载 SandCastle Installer， 并运行安装程序。

注意：

如果想要安装Visual Studio 2008 SDK，请在安装SandCastle之前安装。这是因为Visual Studio 2008 SDK 安装时更新了PATH和DXROOT两个系统注册的变量。如果在SandCastle安装后这两个变量被更新，将导致SandCastle无法工作。如果已经安装了SandCastle，有下面两个方法：

• 安装Visual Studio 2008 SDK后，卸载SandCastle，重新安装SandCastle。
• 重新设置PATH和DXROOT两个环境变量

如果是非x86（32位机器）机器，请参考下文。

在AMD64机器上设置SandCastle

• 在开始菜单上，在“我的电脑”上单击鼠标右键，选择“属性”。
• 在左侧的区域中，单击“高级系统设置”。
• 在“高级”标签中单击“环境变量”按钮。
• 在“环境变量”中找到“PATH”，单击“编辑”。
• 将下面的变量添加到属性值中：
  %ProgramFiles(x86)%\HTML Help Workshop;%ProgramFiles(x86)%\Common Files\Microsoft Shared\Help 2.0 Compiler

转载于:https://www.cnblogs.com/zhangziqiu/archive/2009/12/18/Sandcastle-1.html