用Sandcastle和Help Integration Wizard把文档集成到Visual Studio中
用Sandcastle和Help Integration Wizard把文档集成到Visual Studio
by Freesc Huang
1.准备
在正式开始工作之前，请确保您正确的安装以下软件
1.1 Visual Studio 2005 SP1 SDK (VS2005 SDK 4.0)
1.2 Sandcastle
Sandcastle
http://www.codeplex.com/Sandcastle/
Sandcastle Help File Builder
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），选择“视图”-->“文件系统”然后在该视图中右键“目标计算机上的文件系统”-->“添加特殊文件”在系统的一些特殊文件夹下部署内容：
一切添加完毕后，可以编译该项目了。
4.测试
编译完成之后，双击第３步生成的安装文件，选择好安装路径，（最好关闭Visual Studio和MSDN，确保dexeplorer.exe没有运行），正确安装后，重新打开Visual Studio帮助文档(MSDN)：
在索引里面键入我们项目中的某个类，我们看到过滤出来的结果正是我们之前的项目中的。然后，我们点击“目录”(Content)，看到我们添加的目录也成功了：
ohyeah，大功告成了！
5.参考资源
利用 Sandcastle 编写软件 SDK 文档 - Mark Zhou
使用SandCastle和HTML Help 2.0集成XML代码注释到VS2005和VS2008
Integrate your Framework documentation into Visual Studio Help
Other MSDN Resources
Editing the Help Registration Merge Module
Consuming Help Registration Merge Modules
Getting Started with Help Content and Integration
Deploying Your Help Collection