Sandcastle入门：创建C#帮助文档

今天学到了一个东西：利用vs2005生成的dll/xml来生成帮助文档。

完成这个伟大任务的是Sandcastle，微软推出的类库文档编译工具。

在开始这篇笔记之前，我想先感谢我文后提及的七篇关于Sandcastle的 文章。是它们出色的阐述使得我能够整理出这篇笔记，之前我从未接触过。对于那七篇文章，我努力寻找它们的源出处链接，然而网络的传播性使得这些一再被转载 的文章逐渐模糊了它们的来源，有一些是我无法确定的。因此，我希望，如果这篇文章有幸能被您转载，请注明转载和出处，谢谢。o(∩_∩)o…

　　　

(瑶瑶按：由于本文较长且从word移植到baidu的诸多不便，本文将分成3个部分分别发布）

　　

目录

========================================================================
　　1. 名词解释：Sandcastle---------------------------------------[1]
　　2. Background---------------------------------------------------[1]
　　3. Sandcastle Overview-----------------------------------------[1]
　　4. 使用Sandcastle-----------------------------------------------[2]
　　　　4.1 使用平台

　　4.2 使用方式（可选界面）
　　　　4.3 资源下载

5. 生成文档步骤------------------------------------------------[3]
　　　　5.0 使用命令行方式
　　　　5.1 Sandcastle Help File Builder
　　　　5.2 SandcastleGUI
　　　　5.3 Sandcastle CHM编译BAT脚本和配置实用工具
　　　　5.4 DocProject
　　6. References----------------------------------------------------[3]
　　========================================================================

1.名词解释：Sandcastle

========================================================================

Documentation compilers for managed class libraries

Enabling 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 SDK 类库文档或者 MSDN Library 在线 .NET 类库文档形式的代码文档：

然而遗憾的是，这个项目由于资金等问题，作者Kevin于2006年7月宣布不再投入NDoc开源项目的开发，NDoc停留在1.3的历史版本，无法完全支持.NET 2.0，将渐渐淡出人们的视野。

在发布VS2005之前，MS内部开发了一个用于生成帮助文档的工具。这就是Sandcastle的前身。但是当时编译一次文档就需要十多个钟头，这使得这个工具可用性不强。后来发布的Sandcastle由于做了很大的优化，就只要30分钟了。当然，现在的Sandcastle经历了几个CTP版本的测试已经比较成熟了。（Ref[1]，有增删）（注：CTP，Community Technology Preview）。Sandcastle目前（<chsdate year="2007" month="10" day="30" islunardate="False" isrocdate="False"><span><font face="Times New Roman">2007</font></span><span>年</span><span><font face="Times New Roman">10</font></span><span>月</span><span><font face="Times New Roman">30</font></span><span>日</span></chsdate>）为止最新的版本是September 2007 CTP，version 2.3.07930.06，<chsdate year="2007" month="10" day="1" islunardate="False" isrocdate="False"><span><font face="Times New Roman">2007</font></span><span>年</span><span><font face="Times New Roman">10</font></span><span>月</span><span><font face="Times New Roman">1</font></span><span>日</span></chsdate>发布。（瑶瑶按：在写这篇日志的过程中，MS发布了新的Sandcastle版本October 2007 CTP，version 2.3.8000.26，2007年10月29日发布。相应地后面提到的SandcastleGUI也进行了更新。）

3.Sandcastle Overview

Sandcastle是一个管理类库的文档编译器，是用于编译发布组件（Assembly）信息的一个工具，这个工具通过反射和Xslt技术，可以从dll文件及其xml注释（命令行编译时加/doc参数或vs2005设置项目属性得到）得到一个完整的帮助文档，格式可以是Html或CHM甚至是任何自定义的格式。（Ref[2]，Ref[3]，有增删整合）

Sandcastle与.NET Framework 2.0和.NET Compact Framework组合使用。Sandcastle支持本地化，并提供一个基本的命令行编译器界面和一个Visual Studio插件。（Ref[2]）

4.Sandcastle Process（Ref[2]）

Sandcastle中共有三个组件：MrefBuilder、Build Assembler和XslTransform。这些工具使用编译汇编代码时生成的输出结果，包括DLL文件以及XML注释文件。

MrefBuilder反射一个项目的汇编代码并生成一个输出文件。MrefBuilder是一个随Sandcastle安装的命令行工具。它生成的输出文件通过XslTransform命令行工具转换成一个叫做reflection.xml的文件。reflection.xml文件包含所有文档数据，但不提供显示细节。

MrefBuilder完成工作后，立即由Build Assembler接手处理。Build Assembler可由命令行工具BuildAssembler启动。它利用由MrefBuilder生成的数据(reflection.xml)和任何代码注释（保存在独立的XML文件中），生成按逻辑分组的HTML文件。HTML Help Compiler再利用这些HTML文件生成最终结果。

该工具并未限制你一次处理一个汇编。如果你需要处理几个汇编代码，你必须深入了解Sandcastle配置文件。它是一个包含建立帮助文件主题所需步骤的XML文件。

（图：Sandcastle工作过程）

Sandcastle生成的输出结果具有以下特点：

Ø 类似于MSDN布局的界面。

Ø 自动生成索引项、内容项目表、主题块和页面布局，提高一致性和熟悉程度。

Ø 自动生成语法宣称部分。

Ø 自动生成继承表。

Ø 代码彩色化。

Ø 提供多种风格和语言选择，终端用户可从中选择自己最喜欢的形式。

Ø 输出结果以HTML和CSS形式显示，微软承诺将来提供更多选择。

========================================================================

Overview

Sandcastle produces accurate, MSDN style, comprehensive documentation by reflecting over the source assemblies and optionally integrating XML Documentation Comments. Sandcastle has the following key features:

l Works with or without authored comments

l Supports Generics and .NET Framework 2.0

l Sandcastle has 2 main components (MrefBuilder and Build Assembler)

l MrefBuilder generates reflection xml file for Build Assembler

l Build Assembler includes syntax generation, transformation..etc

l Sandcastle is used internally to build .Net Framework documentation

========================================================================

4.使用Sandcastle

4.1使用平台

（1）操作系统：
Windows Server 2003; Windows XP Service Pack 2; Windows Vista;

（2）必备软件：
Microsoft .NET Framework Version 2.0
HTML Help Workshop——如果需要编译生成CHM文档（需要用到其中的hhc.exe文件）

（3）可选软件：
Visual Studio 2005
MS Help Compiler from VS SDK

4.2使用方式（可选界面）Ref[2]

（0）使用Sandcastle原始的命令行方式

（1）Sandcastle Help File Builder
它提供一个类似于NDoc的界面，允许你输入现有的NDoc项目，自动完成创建过程。

（2）SandcastleGUI
这是一个免费的Sandcastle GUI前端界面。利用它可以在图形界面操作，省去用户输入命令行的麻烦。并且具有以下扩充Ref[6]：
=============================================================================
>>自动在文档中插入MSDN文章链接
>>可以选择程序集中的某个命名空间生成文档，而不是默认的整个程序集
>>多种输出方式：网站、CHM帮助文件或输出二者
>>自定义帮助文档头部（公司LOGO以及产品名称等）
>>自定义帮助文章页脚（版权信息等）
>>在文档中插入自定义的图像
>>文档的代码实例中将C#语法高亮显示
=============================================================================

（3）Sandcastle CHM编译BAT脚本和配置实用工具
这是一个配置实用工具和批处理脚本，由它通过Sandcastle可建立MSDN形式的类文档CHM文件。

（4）DocProject
DocProject drives the Sandcastle help generation tools using the power of Visual Studio 2005/2008 and MSBuild.

4.3资源下载
[1]Sandcastle October 2007 CTP下载地址：（Update：version 2.3.8000.26，Released Date：2007-10-29）
http://www.microsoft.com/downloads/details.aspx?familyid=E82EA71D-DA89-42EE-A715-696E3A4873B2&displaylang=en

[2]HTML Help Workshop下载地址：（version1.4）
http://msdn2.microsoft.com/en-us/library/ms669985.aspx

[3]Sandcastle Help File Builder下载地址：（Update：version1.6.0.1，Released Date：2007-10-31）
http://www.codeplex.com/SHFB/Release/ProjectReleases.aspx?ReleaseId=7543

[4]SandcastleGUI下载地址：（Update：version1.40，Released Date：2007-11）
http://www.inchl.nl/SandcastleGUI/（瑶瑶按：这个需要登记邮箱，再从邮箱获取下载链接）

[5]DocProject下载地址：（version1.8.0，Released Date：2007-10-04，Update：version1.9.0 for October 2007 CTP will be available）
http://www.codeplex.com/DocProject/Release/ProjectReleases.aspx?ReleaseId=6652

5.生成文档步骤

前提：代码文档中使用规范的///注释，具体规范查看MSDN-建议的文档注释标记（C#编程指南）。也可以参看本人另一篇介绍文章：《C#中的XML注释》。

5.0 使用命令行方式

参考文章：Ref[7]
——使用sandcastle自带的例子test.cs来生成CHM文件
==========================================================================

1.在命令行下打开该文档所在的路径。例如：

cd /Program Files/Sandcastle/Examples/Sandcastle

2.编译该C#文件，并从中抽取///注释：/t参数使得其编译为dll文件，/doc参数使得其同时生成包含///注释的comments.xml文档。

csc /t:library /doc:comments.xml test.cs

3.运行MrefBuilder生成中间文件reflection.org

MRefBuilder test.dll /out:reflection.org

4.运行XslTransform将上述中间文件转换成xml格式（vs2005）（瑶瑶按：使用prototype请参阅Ref[7]原文）

XslTransform /xsl:"../../ProductionTransforms/ApplyVSDocModel.xsl" reflection.org /xsl:"../../ProductionTransforms/AddFriendlyFilenames.xsl" /out:reflection.xml

5.生成主题清单

XslTransform /xsl:../../ProductionTransforms/ReflectionToManifest.xsl reflection.xml /out:manifest.xml

6.生成输出目录结构（vs2005）

call ../../Presentation/vs2005/copyOutput.bat

7.运行BuildAssembler生成HTML主题文件

BuildAssembler /config:sandcastle.config manifest.xml

8.生成HTML help项目

XslTransform /xsl:../../ProductionTransforms/ReflectionToChmProject.xsl reflection.xml /out:Output/test.hhp

9.生成中间表格内容（vs2005）

XslTransform /xsl:../../ProductionTransforms/createvstoc.xsl reflection.xml /out:toc.xml

10.生成HTML help项目信息

XslTransform /xsl:../../ProductionTransforms/TocToChmContents.xsl toc.xml /out:Output/test.hhc

XslTransform /xsl:../../ProductionTransforms/ReflectionToChmIndex.xsl reflection.xml /out:Output/test.hhk

11. 运行hhc生成CHM

hhc output/test.hhp

==========================================================================

==========================================================================
Note:7. We are providing VS 2005 transforms under Presentation/VS2005 folder and the transforms shipped with the previous versions under Presentation/Prototype folder.
For building VS2005 format please use sandcastle.config file from C:/Program Files/Sandcastle/Presentation/vs2005/Configuration folder as it uses shared content from C:/Program Files/Sandcastle/Presentation/vs2005/Content and transforms from C:/Program Files/Sandcastle/Presentation/vs2005/Transforms
==========================================================================

5.1 Sandcastle Help File Builder

参考文章：Ref[5]
==========================================================================
1.首先要为项目生成一个包含注释的XML文件
在c#项目中鼠标右键点击所选的项目，选择Properties->Build项，勾选XML documentation file。设置完毕编译项目，就可以生成属于它的xml文件了。
2.打开我们已经安装好的Sandcastle Help File Builder并对它进行设置
　　>>点击Add按钮，选中项目生成的exe,dll,xml文件
　　>>保存该项目后点击Namespaces按钮，选中想要生成帮助文档的Namespace
　　>>设定Dependencies选项，把项目中所引用到的dll文件加载进去
　　>>设置HtmlHelp1xCompilerPath为HTML Help Workshop的安装路径，
　　>>设置SandcastlePath为Sandcastle的安装路径
3.点击顶头菜单Documentation下拉菜单中的Build Project选项（或直接使用快捷键Ctrl+Shift+B）编译即可生成所需的帮助文档
4.该文档的默认输出路径在项目所在目录的Help文件夹下，当然也可以更改Sandcastle Help File Builder中的设置，自己设定它的输入路径。==========================================================================

5.2 SandcastleGUI

以下图片参考文章：Ref[6]（按：新版本的界面有差异，但大体相同。）
界面：

1）生成各项目的*.dll和*.xml文件（在vs2005中编译选项设置，具体前面5.1 Sandcastle Help File Builder的生成步骤中已提及）；
2）将*.dll和*.xml文件放在一个目录A下；将所有要附加的图片（比如类图和时序图）放在另一个并行的目录B下（注意不能有子文件夹）；
3）启动SandcastleGUI，设置：
Directory that contains assemblies to document项选择目录A；
Output directory项选择一个空文件夹，如C；
Directory to include in documentation项选择目录B；
其它如C#语法、是否包含C#例子、生成文档类型（website或chm）等选项根据需要填。
4）设置完成后最好Save settings，因为可能常常要用到。然后Start documenting。
5）等待生成完成后就可以在C目录下找到chm文件了：

5.3 Sandcastle CHM编译BAT脚本和配置实用工具

未找到相关文章

5.4 DocProject

参考文章：Ref[4]
——使用MSDN上包含有标准注释的XML文档生成帮助文件示例
==========================================================================
1 先编写一个类库，这里使用的是MSDN上包含有标准注释的"XML文档"示例
2 打开下载到的工程文件, 打开XMLsample.cs, 可以看到各种注释的详细解释

3.使用DocProject方式, 在确保安装了DocProject后, 为工程添加新项目

==> ==> ==> ==>

4.编译DocProject前, 务必使你所要生成文档的类库编译输出注释的XML文件, 详细方法请查看在Visual Studio中生成“XML文档”示例
5.编译DocProject项目, 等待十几分钟(似乎有点慢, 即使类库很小), 就会在该项目下看到HTML版和CHM版的文档了。
==========================================================================

6.References

Ref[1]：Sandcastle：NDoc的继承人
By Lex Mark（李杨），2006-11-12
http://tb.blog.csdn.net/TrackBack.aspx?PostId=1380172

Ref[2]：用微软Sandcastle创建.NET文档
builder.com.cn，2007-04-13
http://www.builder.com.cn/2007/0413/386855.shtml
英文原文：Create .NET documentation with Microsoft's Sandcastle
By Tony Patton，2007-04-10
http://articles.techrepublic.com.com/5100-3513-6174811.html

Ref[3]：Sandcastle初探——官方版的NDoc
冬冬，2006-08-19
http://www.cnblogs.com/yuandong/archive/2006/08/19/481371.html

Ref[4]：使用Sandcastle创建你的类库文档
By MK2，2007-06-26
http://www.cnblogs.com/fengmk2/archive/2007/06/26/Create-your-classes-Library-doc-using-Sandcastle.html（未确定来源）

Ref[5]：Sandcastle创建帮助文档
By justgarden，2006-12-23
http://blog.sina.com.cn/s/blog_4b756451010006n4.html（未确定来源）

Ref[6]：创建专业级别的类库使用文档——Sandcastle十一月份CTP发布
By Dflying Chen，2006-11-13
http://www.cnblogs.com/dflying/archive/2006/11/13/558751.html

Ref[7]：Creating a Chm build using Sandcastle
By aram，2006-07-29
https://blogs.msdn.com/sandcastle/archive/2006/07/29/682398.aspx

***************************************************************************************************************

结语：

衷心感谢以上文章，很多图片都引用自原文。为了保持本文叙述风格的一致，对原文进行了一些细小的增删，望原作者见谅。

***************************************************************************************************************