用Sandcastle和Help Integration Wizard把文档集成到Visual Studio中

用Sandcastle和Help Integration Wizard把文档集成到Visual Studio

by Freesc Huang

http://fox23.cnblogs.com

1.准备

在正式开始工作之前，请确保您正确的安装以下软件

1.1 Visual Studio 2005 SP1 SDK (VS2005 SDK 4.0)

http://www.microsoft.com/downloads/details.aspx?familyid=51A5C65B-C020-4E08-8AC0-3EB9C06996F4&displaylang=en

1.2 Sandcastle

Sandcastle

http://www.codeplex.com/Sandcastle/

Sandcastle Help File Builder

http://www.codeplex.com/SHFB/

2.生成Microsoft帮助文档

以使用Sandcastle为例

2.1使用XML文档注释你的代码

在Visual Studio里面，类，字段和方法前面可以加上如图示的XML注释

2.2项目编译配置

在项目属性的build一栏中，我们需要将XML文档输出钩上：

设置好路径后，编译我们的项目

2.3 使用Sandcastle Help File Builder

SHFB是Sandcastle的GUI工具。

创建新项目（默认叫unnamed）：

点击右上方的“Add”添加你的程序集和之前生成的XML文档到该项目中，如果你的XML注释文档也生成在与程序集相同的目录下（默认就是如此），SHFB会在你添加程序集时自动找到对应的XML文档：

添加后如“MyAssembly.dll, MyAssembly.xml”而不是“MyAssembly.dll, Unknown.xml”。如果没有XML注释文件，那么帮助文档将不会被生成。配置Sandcastle Help Builder如下：

Build

Ø Help File Format: 选择 HtmlHelp2x，这里可以多选。

Ø Dependencies: 添加所有你程序集依赖的程序集

Ø Framework Version: 选择程序集的.NET Framework版本，这里我们选择2.0.50727

Help File

Ø Presentation Style: 选择VS2005样式

Paths

Ø HtmlHelp2xCompilerPath: 选择hxcomp.exe文件所在的目录（仅当SHFB自己找不到hxcomp时需要设置）

Ø SandcastlePath: 选择Sandcastle的安装目录（仅当SHFB自己找不到Sandcastle时需要设置）

Ø OutputPath: 选择你输出文件的路径。

当然，你还可以针对你的需求再进行一些其它配置，比如copyright，header等等。然后保存文档并点击左上的build按钮来生成我们要的帮助文档。一般来说，这一步需要好几分钟的时间，如果你的程序集比较多，这一步有可能需要更长时间，请耐心等待。注意在下方的Output文本框中查看Build的详细信息，如果failed的话，这里会提示你出错的原因。

3.在Visual Studio里面创建安装工程

运行Visual Studio，选择“文件” --> “新项目” --> “其它项目类型” --> “扩展性” -- > “Help Integration Wizard”，注意这里的“扩展性”部分必须是安装过Visual Studio SDK才能看到扩展的内容：

这里我们将该工程命名为“GeminiHelpSetupDemo”，并点击确定。在接下来的对话框中选择“Setup Project”，“Target”这里我们选择“Visual Studio 2005”：

点击“Next”，在新的对话框中点击“Add”添加之前用SHFB生成的.HxS文件：

点击“Next”继续，此时弹出的对话框是对Table of Content(TOC)的编辑，如果你不准备编辑Content使之出现在文档的“目录”（content）列表中，你可以直接点击Next跳过这一步。这里我们暂且选择“Hierarchical”（树形层状结构，当然你也可以选择‘flat’平铺结构），给根节点起名为“GeminiSDKHelpDemo”，如图：

然后点击左上方蓝色的书本图标，插入一个节点，如图：

右键这个节点，点击“Properties”，在弹出的对话框中，从我们的文档中选择这个节点对应的htm文件，如图：

Tips如果你需要详细编辑你自己的Content table我建议您使用HelpStudio Lite，这个工具易经集成到Visual Studio SDK中去了，安装VS SDK时可以选择安装，它的使用方式在MSDN里有详细的说明：http://msdn.microsoft.com/en-us/library/cc138528.aspx

然后，点击“ok”确定，并点击“Next”进行下一步也是向导的最后一步，我们简单设置一下命名空间，如图：

点击“Finish”，完成项目创建。

这时我们之前创建的帮助文档已经由Visual Studio Help Integration Wizard添加到我们的solution里面了，放在一个MergeModule的项目下，后面的操作和一般的安装包工程一样了，这时你可以立即编译，也可以再把咱们的一些程序集加到，右键咱们的安装工程（不是Mergemodule），选择“视图”-->“文件系统”然后在该视图中右键“目标计算机上的文件系统”-->“添加特殊文件”在系统的一些特殊文件夹下部署内容：