使用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选项
[1] [2] 下一页
（或直接使用快捷键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版的文档了。
上一页 [1] [2]
