利用SandCastle生成帮助文档.pdf

该【利用SandCastle生成帮助文档 】是由【小s】上传分享，文档一共【10】页，该文档可以免费在线阅读，需要了解更多关于【利用SandCastle生成帮助文档 】的内容，可以使用淘豆网的站内搜索功能，选择自己适合的文档，以下文字是截取该文章内的部分文字，如需要获得完整电子版，请下载此文档到您的设备，方便您编辑和打印。Sandcastle入门:创建C#帮助文档
今天学到了一个东西:利用vs2005生成的dll/xml来生成帮助文档。
完成这个伟大任务的是Sandcastle,微软推出的类库文档编译工具。
在开始这篇笔记之前,我想先感谢我文后提及的七篇关于Sandcastle的文章。是它们出
色的阐述使得我能够整理出这篇笔记,之前我从未接触过。对于那七篇文章,我努力寻找它
们的源出处链接,然而网络的传播性使得这些一再被转载的文章逐渐模糊了它们的来源,有
一些是我无法确定的。因此,我希望,如果这篇文章有幸能被您转载,请注明转载和出处,
谢谢。o(∩_∩)o…
(瑶瑶按:由于本文较长且从word移植到baidu的诸多不便,本文将分成3个部分分别
发布)
目录
==================================================================
======
:Sandcastle---------------------------------------[1]
---------------------------------------------------[1]
-----------------------------------------[1]
-----------------------------------------------[2]

(可选界面)

------------------------------------------------[3]





----------------------------------------------------[3]
======================================================================
==
名词解释:

======================================================================
==
Documentationcompilersformanagedclasslibraries
Enablingmanagedclasslibrarydevelopersthroughouttheworldtoeasilycreateaccurate,
informativedocumentationwithacommonlookandfeel.
========================================================================

在微软推出Sandcastle之前,人们倾向于选择开源的NDoc(.NET代码文档生成器)。
NDoc可以将C#.NET编译生成的程序集和对应的/docXML文档,
:
然而遗憾的是,这个项目由于资金等问题,作者Kevin于2006年7月宣布不再投入NDoc
开源项目的开发,,,将渐渐淡出人们
的视野。
在发布VS2005之前,MS内部开发了一个用于生成帮助文档的工具。这就是Sandcastle
的前身。但是当时编译一次文档就需要十多个钟头,这使得这个工具可用性不强。后来发布
的Sandcastle由于做了很大的优化,就只要30分钟了。当然,现在的Sandcastle历了经几
个CTP版本的测试已经比较成熟了。(Ref[1],有增删)(注:CTP,CommunityTechnology
Preview)。Sandcastle目前(2007年10月30日)为止最新的版本是September2007CTP,
,2007年10月1日发布。(瑶瑶按:在写这篇日志的过程中,MS发布
了新的Sandcastle版本October2007CTP,,2007年10月29日发布。相
应地后面提到的SandcastleGUI也进行了更新。)

Sandcastle是一个管理类库的文档编译器,是用于编译发布组件(Assembly)信息的一
个工具,这个工具通过反射和Xslt技术,可以从dll文件及其xml注释(命令行编译时加/doc
参数或vs2005设置项目属性得到)得到一个完整的帮助文档,格式可以是Html或CHM甚
至是任何自定义的格式。(Ref[2],Ref[3],有增删整合)
。Sandcastle支持
本地化,并提供一个基本的命令行编译器界面和一个VisualStudio插件。(Ref[2])
(Ref[2])
Sandcastle中共有三个组件:MrefBuilder、BuildAssembler和XslTransform。这些工具
使用编译汇编代码时生成的输出结果,包括DLL文件以及XML注释文件。
MrefBuilder反射一个项目的汇编代码并生成一个输出文件。MrefBuilder是一个随
Sandcastle安装的命令行工具。它生成的输出文件通过XslTransform命令行工具转换成一个
。,但不提供显示细节。
MrefBuilder完成工作后,立即由BuildAssembler接手处理。BuildAssembler可由命令
行工具BuildAssembler启动。它利用由MrefBuilder生成的数据()和任何代码注
释(保存在独立的XML文件中),生成按逻辑分组的HTML文件。HTMLHelpCompiler
再利用这些HTML文件生成最终结果。
该工具并未限制你一次处理一个汇编。如果你需要处理几个汇编代码,你必须深入了解
Sandcastle配置文件。它是一个包含建立帮助文件主题所需步骤的XML文件。
(图:Sandcastle工作过程)
Sandcastle生成的输出结果具有以下特点:
Ø类似于MSDN布局的界。面
Ø自动生成索引项、内容项目表、主题块和页面布局,提高一致性和熟悉程度。
Ø自动生成语法宣称部分。
Ø自动生成继承表。
Ø代码彩色化。
Ø提供多种风格和语言选择,终端用户可从中选择自己最喜欢的形式。
Ø输出结果以HTML和CSS形式显示,微软承诺将来提供更多选择。
=============================================================
===========
Overview
Sandcastleproducesaccurate,MSDNstyle,comprehensivedocumentationbyreflectingoverthe

followingkeyfeatures:
lWorkswithorwithoutauthoredcomments

lSandcastlehas2maincomponents(MrefBuilderandBuildAssembler)
lMrefBuildergeneratesreflectionxmlfileforBuildAssembler
lBuildAssemblerincludessyntaxgeneration,transformation..etc

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


(1)操作系统:
WindowsServer2003;WindowsXPServicePack2;WindowsVista;
(2)必备软件:

HTMLHelpWorkshop——如果需要编译生成CHM文档(需要用到其中的
)
(3)可选软件:
VisualStudio2005
MSHelpCompilerfromVSSDK
(可选界面)Ref[2]
(0)使用Sandcastle原始的命令行方式
(1)SandcastleHelpFileBuilder
它提供一个类似于NDoc的界面,允许你输入现有的NDoc项目,自动完成创建
过程。
(2)SandcastleGUI
这是一个免费的SandcastleGUI前端界面。利用它可以在图形界面操作,省去用
户输入命令行的麻烦。并且具有以下扩充Ref[6]:
=============================================================
================
>>自动在文档中插入MSDN文章链接
>>可以选择程序集中的某个命名空间生成文档,而不是默认的整个程序集
>>多种输出方式:网站、CHM帮助文件或输出二者
>>自定义帮助文档头部(公司LOGO以及产品名称等)
>>自定义帮助文章页脚(版权信息等)
>>在文档中插入自定义的图像
>>文档的代码实例中将C#语法高亮显示
=============================================================
================
(3)SandcastleCHM编译BAT脚本和配置实用工具
这是一个配置实用工具和批处理脚本,由它通过Sandcastle可建立MSDN形式
的类文档CHM文件。
(4)DocProject
DocProjectdrivestheSandcastlehelpgenerationtoolsusingthepowerofVisual
Studio2005/2008andMSBuild.

[1]SandcastleOctober2007CTP下载地址:(Update:,Released
Date:2007-10-29)
?familyid=E82EA71D-DA89-42EE
-A715-696E3A4873B2&displaylang=en
[2]HTMLHelpWorkshop下载地址:()
-us/library/
[3]SandcastleHelpFileBuilder下载地址:(Update:,ReleasedDate:
2007-10-31)
?ReleaseId=7543
[4]SandcastleGUI下载地址:(Update:,ReleasedDate:2007-11)
/(瑶瑶按:这个需要登记邮箱,再从邮箱获取
下载链接)
[5]DocProject下载地址:(,ReleasedDate:2007-10-04,Update:
)
?ReleaseId=6652

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

参考文章:Ref[7]
——
=============================================================
=============
。例如:
cd\ProgramFiles\Sandcastle\Examples\Sandcastle
#文件,并从中抽取///注释:/t参数使得其编译为dll文件,/doc参数使得其同时生成
包含///。
csc/t:library/doc:

:
(vs2005)(瑶瑶按:使用prototype请参
阅Ref[7]原文)
XslTransform/xsl:"..\..\ProductionTransforms\"
/xsl:"..\..\ProductionTransforms\"/out:

XslTransform/xsl:..\..\ProductionTransforms\
/out:
(vs2005)
call..\..\Presentation\vs2005\

BuildAssembler/config:

XslTransform/xsl:..\..\ProductionTransforms\
/out:Output\
(vs2005)
XslTransform/xsl:..\..\ProductionTransforms\:

XslTransform/xsl:..\..\ProductionTransforms\
/out:Output\
XslTransform/xsl:..\..\ProductionTransforms\
/out:Output\

hhcoutput\
=============================================================
=============
=============================================================
=============
Note:
shippedwiththepreviousversionsunderPresentation/Prototypefolder.
:\Program
Files\Sandcastle\Presentation\vs2005\ConfigurationfolderasitusessharedcontentfromC:\Program
Files\Sandcastle\Presentation\vs2005\ContentandtransformsfromC:\Program
Files\Sandcastle\Presentation\vs2005\Transforms
=============================================================
=============

参考文章:Ref[5]
=============================================================
=============

在c#项目中鼠标右键点击所选的项目,选择Properties->Build项,勾选XML
documentationfile。设置完毕编译项目,就可以生成属于它的xml文件了。

>>点击Add按钮,选中项目生成的exe,dll,xml文件
>>保存该项目后点击Namespaces按钮,选中想要生成帮助文档的
Namespace
>>设定Dependencies选项,把项目中所引用到的dll文件加载进去
>>设置HtmlHelp1xCompilerPath为HTMLHelpWorkshop的安装路径,
>>设置SandcastlePath为Sandcastle的安装路径
(或直接使用快
捷键Ctrl+Shift+B)编译即可生成所需的帮助文档
,当然也可以更改
SandcastleHelpFileBuilder中的设置,自己设定它的输入路径。
=============================================================
=============

以下图片参考文章:Ref[6](按:新版本的界面有差异,但大体相同。)
界面:
1)生成各项目的*.dll和*.xml文件(在vs2005中编译选项设置,
SandcastleHelpFileBuilder的生成步骤中已提及);
2)将*.dll和*.xml文件放在一个目录A下;将所有要附加的图片(比如类图和
时序图)放在另一个并行的目录B下(注意不能有子文件夹);
3)启动SandcastleGUI,设置:
Directorythatcontainsassembliestodocument项选择目录A;
Outputdirectory项选择一个空文件夹,如C;
Directorytoincludeindocumentation项选择目录B;
其它如C#语法、是否包含C#例子、生成文档类型(website或chm)等选项根
据需要填。
4)设置完成后最好Savesettings,因为可能常常要用到。然后Startdocumenting。
5)等待生成完成后就可以在C目录下找到chm文件了:

未找到相关文章

参考文章:Ref[4]
——使用MSDN上包含有标准注释的XML文档生成帮助文件示例
=============================================================
=============
1先编写一个类库,这里使用的是MSDN上包含有标准注释的"XML文档"示例
2打开下载到的工程文件,,可以看到各种注释的详细解释
,在确保安装了DocProject后,为工程添加新项目
==>==>
==>==>
,务必使你所要生成文档的类库编译
输出注释的XML文件,详细方法请查看在VisualStudio中生成“XML文档”示例
,等待十几分钟(似乎有点慢,即使类库很小),就会在该项
目下看到HTML版和CHM版的文档了。
=============================================================
=============

Ref[1]:Sandcastle:NDoc的继承人
ByLexMark(李杨),2006-11-12
?PostId=1380172
Ref[2]:
,2007-04-13

英文原文:'sSandcastle
ByTonyPatton,2007-04-10
-3513-
Ref[3]:Sandcastle初探——官方版的NDoc
冬冬,2006-08-19

Ref[4]:使用Sandcastle创建你的类库文档
ByMK2,2007-06-26
-your-classes-Library-do
c-using-(未确定来源)
Ref[5]:Sandcastle创建帮助文档
Byjustgarden,2006-12-23
(未确定来源)
Ref[6]:创建专业级别的类库使用文档——Sandcastle十一月份CTP发布
ByDflyingChen,2006-11-13

Ref[7]:CreatingaChmbuildusingSandcastle
Byaram,2006-07-29

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