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

概要

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

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

 

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

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

一.SandCastle介绍

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

生成的文档如下图所示：

image_thumb_4[1]

二. 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
    posted @ 2009-12-18 11:53  ziqiu.zhang  阅读(8565)  评论(11)  编辑  收藏  举报