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 阅读(...) 评论(...) 编辑 收藏