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

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

　　使用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

　　生成文档步骤

　　前提：代码文档中使用规范的///注释，具体规范查看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.xmltest.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 providingVS 2005 transformsunder Presentation/VS2005 folder and the transforms shipped with the previous versions under Presentation/Prototype folder.

　　For building VS2005 format please usesandcastle.configfile fromC:\Program Files\Sandcastle\Presentation\vs2005\Configurationfolder as it uses shared content fromC:\Program Files\Sandcastle\Presentation\vs2005\Contentand transforms fromC:\Program Files\Sandcastle\Presentation\vs2005\Transforms

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

　　5.1 Sandcastle Help File Builder

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

　　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

　　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版的文档了。

 

引用“http://www.inchl.net/redirect/?id=9ebb1a233cab410dafa599ca89335fcd&action=link”