《利用sandcastle生成帮助文档》由会员分享，可在线阅读，更多相关《利用sandcastle生成帮助文档（10页珍藏版）》请在金锄头文库上搜索。
1、Sandcastle 入门：创建 C#帮助文档 今天学到了一个东西：利用 vs2005生成的 dll/xml来生成帮助文档。完成这个伟大任务的是 Sandcastle，微软推出的类库文档编译工具。在开始这篇笔记之前，我想先感谢我文后提及的七篇关于 Sandcastle的文章。是它们出色的阐述使得我能够整理出这篇笔记，之前我从未接触过。对于那七篇文章，我努力寻找它们的源出处链接，然而网络的传播性使得这些一再被转载的文章逐渐模糊了它们的来源，有一些是我无法确定的。因此，我希望，如果这篇文章有幸能被您转载，请注明转载和出处，谢谢。o(_)o(瑶瑶按：由于本文较长且从 word移植到 baidu的诸多
2、不便，本文将分成 3个部分分别发布）目录=1. 名词解释：Sandcastle-12. Background-13. Sandcastle Overview-14. 使用 Sandcastle-24.1 使用平台4.2 使用方式（可选界面）4.3 资源下载5. 生成文档步骤-35.0 使用命令行方式5.1 Sandcastle Help File Builder5.2 SandcastleGUI5.3 Sandcastle CHM 编译 BAT脚本和配置实用工具5.4 DocProject6. References-3=1.名词解释：Sandcastle=Documentation compi
3、lers for managed class librariesEnabling managed class library developers throughout the world to easily create accurate, informative documentation with a common look and feel.=2.Background在微软推出 Sandcastle之前，人们倾向于选择开源的 NDoc（.NET 代码文档生成器）。NDoc可以将 C#.NET 编译生成的程序集和对应的 /doc XML 文档，自动转换成如 .NET Framework
4、SDK 类库文档或者 MSDN Library 在线 .NET 类库文档形式的代码文档：然而遗憾的是，这个项目由于资金等问题，作者 Kevin于 2006年 7月宣布不再投入 NDoc开源项目的开发，NDoc 停留在 1.3的历史版本，无法完全支持.NET 2.0，将渐渐淡出人们的视野。在发布 VS2005之前，MS 内部开发了一个用于生成帮助文档的工具。这就是Sandcastle的前身。但是当时编译一次文档就需要十多个钟头，这使得这个工具可用性不强。后来发布的 Sandcastle由于做了很大的优化，就只要 30分钟了。当然，现在的Sandcastle经历了几个 CTP版本的测试已经比较成熟
5、了。（Ref1，有增删）（注：CTP，Community Technology Preview）。Sandcastle 目前（2007 年 10月 30日）为止最新的版本是 September 2007 CTP，version 2.3.07930.06，2007 年 10月 1日发布。（瑶瑶按：在写这篇日志的过程中，MS 发布了新的 Sandcastle版本 October 2007 CTP，version 2.3.8000.26，2007 年 10月 29日发布。相应地后面提到的 SandcastleGUI也进行了更新。）3.Sandcastle OverviewSandcastle是一个管
6、理类库的文档编译器，是用于编译发布组件（Assembly）信息的一个工具，这个工具通过反射和 Xslt技术，可以从 dll文件及其 xml注释（命令行编译时加/doc 参数或 vs2005设置项目属性得到）得到一个完整的帮助文档，格式可以是Html或 CHM甚至是任何自定义的格式。（Ref2，Ref3，有增删整合）Sandcastle与.NET Framework 2.0 和.NET Compact Framework 组合使用。Sandcastle支持本地化，并提供一个基本的命令行编译器界面和一个 Visual Studio插件。（Ref2）4.Sandcastle Process（Ref2
7、）Sandcastle中共有三个组件：MrefBuilder、Build Assembler 和 XslTransform。这些工具使用编译汇编代码时生成的输出结果，包括 DLL文件以及 XML注释文件。MrefBuilder反射一个项目的汇编代码并生成一个输出文件。MrefBuilder 是一个随Sandcastle安装的命令行工具。它生成的输出文件通过 XslTransform命令行工具转换成一个叫做 reflection.xml的文件。reflection.xml 文件包含所有文档数据，但不提供显示细节。MrefBuilder完成工作后，立即由 Build Assembler接手处理。B
8、uild Assembler 可由命令行工具 BuildAssembler启动。它利用由 MrefBuilder生成的数据(reflection.xml)和任何代码注释（保存在独立的 XML文件中），生成按逻辑分组的 HTML文件。HTML Help Compiler再利用这些 HTML文件生成最终结果。该工具并未限制你一次处理一个汇编。如果你需要处理几个汇编代码，你必须深入了解 Sandcastle配置文件。它是一个包含建立帮助文件主题所需步骤的 XML文件。（图：Sandcastle 工作过程）Sandcastle生成的输出结果具有以下特点： 类似于 MSDN布局的界面。 自动生成索引项、
9、内容项目表、主题块和页面布局，提高一致性和熟悉程度。 自动生成语法宣称部分。 自动生成继承表。 代码彩色化。 提供多种风格和语言选择，终端用户可从中选择自己最喜欢的形式。 输出结果以 HTML和 CSS形式显示，微软承诺将来提供更多选择。=OverviewSandcastle produces accurate, MSDN style, comprehensive documentation by reflecting over the source assemblies and optionally integrating XML Documentation Comments. Sandca
10、stle has the following key features:l Works with or without authored commentsl Supports Generics and .NET Framework 2.0l Sandcastle has 2 main components (MrefBuilder and Build Assembler)l MrefBuilder generates reflection xml file for Build Assemblerl Build Assembler includes syntax generation, tran
11、sformation.etcl Sandcastle is used internally to build .Net Framework documentation=4.使用 Sandcastle4.1使用平台（1）操作系统：Windows Server 2003; Windows XP Service Pack 2; Windows Vista;（2）必备软件：Microsoft .NET Framework Version 2.0HTML Help Workshop如果需要编译生成 CHM文档（需要用到其中的hhc.exe文件）（3）可选软件：Visual Studio 2005MS H
12、elp Compiler from VS SDK4.2使用方式（可选界面）Ref2（0）使用 Sandcastle原始的命令行方式（1）Sandcastle Help File Builder它提供一个类似于 NDoc的界面，允许你输入现有的 NDoc项目，自动完成创建过程。（2）SandcastleGUI这是一个免费的 Sandcastle GUI前端界面。利用它可以在图形界面操作，省去用户输入命令行的麻烦。并且具有以下扩充 Ref6：=自动在文档中插入 MSDN文章链接 可以选择程序集中的某个命名空间生成文档，而不是默认的整个程序集 多种输出方式：网站、CHM 帮助文件或输出二者 自定义帮
13、助文档头部（公司 LOGO以及产品名称等） 自定义帮助文章页脚（版权信息等） 在文档中插入自定义的图像 文档的代码实例中将 C#语法高亮显示=（3）Sandcastle CHM 编译 BAT脚本和配置实用工具这是一个配置实用工具和批处理脚本，由它通过 Sandcastle可建立 MSDN形式的类文档 CHM文件。（4）DocProjectDocProject drives the Sandcastle help generation tools using the power of Visual Studio 2005/2008 and MSBuild.4.3资源下载1Sandcastle October 2007 CTP下载地址：（Update：version 2.3.8000.26，Released Date：2007-10-
