Sandcastle入门:创建C#帮助文档
  
今天学到了一个东西:利用vs2005生成的dll/xml来生成帮助文档。
完成这个伟大任务的是Sandcastle,微软推出的类库文档编译工具。
在开始这篇笔记之前,我想先感谢我文后提及的七篇关于Sandcastle的文章。是它们出色的阐述使得我能够整理出这篇笔记,之前我从未接触过。对于那七篇文章,我努力寻找它们的源出处链接,然而网络的传播性使得这些一再被转载的文章逐渐模糊了它们的来源,有一些是我无法确定的。因此,我希望,如果这篇文章有幸能被您转载,请注明转载和出处,谢谢。o(∩_∩)o…
   
(瑶瑶按:由于本文较长且从word移植到baidu的诸多不便,本文将分成3个部分分别发布)
  
目录
========================================================================   
1. 名词解释:Sandcastle---------------------------------------[1]   
2. Background---------------------------------------------------[1]   
3. Sandcastle Overview-----------------------------------------[1]   
4. 使用Sandcastle-----------------------------------------------[2]     
 
4.1 使用平台
  4.2 使用方式(可选界面)     
  4.3 资源下载
5. 生成文档步骤------------------------------------------------[3]     
  5.0 使用命令行方式     
  5.1 Sandcastle Help File Builder     
  5.2 SandcastleGUI     
  5.3 Sandcastle CHM编译BAT脚本和配置实用工具     
  5.4 DocProject   
 
6. References----------------------------------------------------[3]   ========================================================================
1.名词解释:Sandcastle
========================================================================
Documentation compilers for managed class libraries
Enabling managed class library developers throughout the world to easily create accurate, informative documentation with a common look and feel.
========================================================================
2.Background
在微软推出Sandcastle之前,人们倾向于选择开源的NDoc(.NET代码文档生成器)。NDoc可以将 C#.NET 编译生成的程序集和对应的 /doc XML文档,自动转换成如 .NET Framework SDK 类库文档或者 MSDN Library 在线 .NET 类库文档形式的代码文档:
 
然而遗憾的是,这个项目由于资金等问题,作者Kevin于2006年7月宣布不再投入NDoc开源项目的开发,NDoc停留在1.3的历史版本,无法完全支持.NET 2.0,将渐渐淡出人们的视野。
在发布VS2005之前,MS内部开发了一个用于生成帮助文档的工具。这就是Sandcastle的前身。但是当时编译一次文档就需要十多个钟头,这使得这个工具可用性不强。后来发布的Sandcastle由于做了很大的优化,就只要30分钟了。当然,现在的Sandcastle经历了几个CTP版本的测试已经比较成熟了。(Ref[1],有增删)(注:CTP,Community Technology Preview)。Sandcastle目前(2007年10月30日)为止最新的版本是September 2007 CTP,version 2.3.07930.06,2007年10月1日发布。(瑶瑶按:在写这篇日志的过程中,MS发布了新的Sandcastle版本October 2007 CTP,version 2.3.8000.26,2007年10月29日发布。相应地后面提到的SandcastleGUI也进行了更新。)
3.Sandcastle Overview
       Sandcastle是一个管理类库的文档编译器,是用于编译发布组件(Assembly)信息的一个工具,这个工具通过反射和Xslt技术,可以从dll文件及其xml注释(命令行编译时加/doc参数或vs2005设置项目属性得到)得到一个完整的帮助文档,格式可以是Html或CHM甚至是任何自定义的格式。(Ref[2]Ref[3],有增删整合)
Sandcastle与.NET Framework 2.0和.NET Compact Framework组合使用。Sandcastle支持本地化,并提供一个基本的命令行编译器界面和一个Visual Studio插件。(Ref[2]
4.Sandcastle Process(Ref[2]
Sandcastle中共有三个组件:MrefBuilder、Build Assembler和XslTransform。这些工具使用编译汇编代码时生成的输出结果,包括DLL文件以及XML注释文件。
MrefBuilder反射一个项目的汇编代码并生成一个输出文件。MrefBuilder是一个随Sandcastle安装的命令行工具。它生成的输出文件通过XslTransform命令行工具转换成一个叫做reflection.xml的文件。reflection.xml文件包含所有文档数据,但不提供显示细节。
MrefBuilder完成工作后,立即由Build Assembler接手处理。Build Assembler可由命令行工具BuildAssembler启动。它利用由MrefBuilder生成的数据(reflection.xml)和任何代码注释(保存在独立的XML文件中),生成按逻辑分组的HTML文件。HTML Help Compiler再利用这些HTML文件生成最终结果。
该工具并未限制你一次处理一个汇编。如果你需要处理几个汇编代码,你必须深入了解Sandcastle配置文件。它是一个包含建立帮助文件主题所需步骤的XML文件。
 
(图:Sandcastle工作过程)
Sandcastle生成的输出结果具有以下特点:
Ø         类似于MSDN布局的界面。
Ø         自动生成索引项、内容项目表、主题块和页面布局,提高一致性和熟悉程度。
Ø         自动生成语法宣称部分。
Ø         自动生成继承表。
Ø         代码彩色化。
Ø         提供多种风格和语言选择,终端用户可从中选择自己最喜欢的形式。
Ø         输出结果以HTML和CSS形式显示,微软承诺将来提供更多选择。
========================================================================
Overview
Sandcastle produces accurate, MSDN style, comprehensive documentation by reflecting over the source assemblies and optionally integrating XML Documentation Comments. Sandcastle has the following key features:
l         Works with or without authored comments
l         Supports Generics and .NET Framework 2.0
l         Sandcastle has 2 main components (MrefBuilder and Build Assembler)
l         MrefBuilder generates reflection xml file for Build Assembler
l         Build Assembler includes syntax generation, transformation..etc
l         Sandcastle is used internally to build .Net Framework documentation
========================================================================

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

4.3资源下载 [1]Sandcastle October 2007 CTP下载地址:(Update:version 2.3.8000.26,Released Date:2007-10-29) http://www.microsoft.com/downloads/details.aspx?familyid=E82EA71D-DA89-42EE-A715-696E3A4873B2&displaylang=en

[2]HTML Help Workshop下载地址:(version1.4) http://msdn2.microsoft.com/en-us/library/ms669985.aspx

[3]Sandcastle Help File Builder下载地址:(Update:version1.6.0.1,Released Date:2007-10-31) http://www.codeplex.com/SHFB/Release/ProjectReleases.aspx?ReleaseId=7543

[4]SandcastleGUI下载地址:(Update:version1.40,Released Date:2007-11) http://www.inchl.nl/SandcastleGUI/(瑶瑶按:这个需要登记邮箱,再从邮箱获取下载链接)

[5]DocProject下载地址:(version1.8.0,Released Date:2007-10-04,Update:version1.9.0 for October 2007 CTP will be available) http://www.codeplex.com/DocProject/Release/ProjectReleases.aspx?ReleaseId=6652

5.生成文档步骤
前提:代码文档中使用规范的///注释,具体规范查看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.xml test.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 providing VS 2005 transforms under Presentation/VS2005 folder and the transforms shipped with the previous versions under Presentation/Prototype folder. For building VS2005 format please use sandcastle.config file from C:/Program Files/Sandcastle/Presentation/vs2005/Configuration folder as it uses shared content from C:/Program Files/Sandcastle/Presentation/vs2005/Content and transforms from C:/Program Files/Sandcastle/Presentation/vs2005/Transforms ==========================================================================
5.1 Sandcastle Help File Builder
参考文章:Ref[5] ========================================================================== 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
以下图片参考文章:Ref[6](按:新版本的界面有差异,但大体相同。) 界面:
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版的文档了。 ==========================================================================
6.References
Ref[1]:Sandcastle:NDoc的继承人 By Lex Mark(李杨),2006-11-12 http://tb.blog.csdn.net/TrackBack.aspx?PostId=1380172
Ref[2]:用微软Sandcastle创建.NET文档 builder.com.cn,2007-04-13 http://www.builder.com.cn/2007/0413/386855.shtml 英文原文:Create .NET documentation with Microsoft's Sandcastle By Tony Patton,2007-04-10 http://articles.techrepublic.com.com/5100-3513-6174811.html
Ref[3]:Sandcastle初探——官方版的NDoc 冬冬,2006-08-19 http://www.cnblogs.com/yuandong/archive/2006/08/19/481371.html
Ref[4]:使用Sandcastle创建你的类库文档 By MK2,2007-06-26 http://www.cnblogs.com/fengmk2/archive/2007/06/26/Create-your-classes-Library-doc-using-Sandcastle.html(未确定来源)
Ref[5]:Sandcastle创建帮助文档 By justgarden,2006-12-23 http://blog.sina.com.cn/s/blog_4b756451010006n4.html(未确定来源)
Ref[6]:创建专业级别的类库使用文档——Sandcastle十一月份CTP发布 By Dflying Chen,2006-11-13 http://www.cnblogs.com/dflying/archive/2006/11/13/558751.html
Ref[7]:Creating a Chm build using Sandcastle By aram,2006-07-29 https://blogs.msdn.com/sandcastle/archive/2006/07/29/682398.aspx
***************************************************************************************************************

转自:http://hi.baidu.com/czlaner/blog/item/c4976d466db6370a6a63e56e.html

Sandcastle入门:创建C#帮助文档的更多相关文章

  1. 使用SandCastle创建.Net帮助文档

    使用SandCastle创建.Net帮助文档 引用自:http://www.cnblogs.com/DotNetNuke/archive/2009/04/23/1441899.html Sandcas ...

  2. 转 创建 JavaScript XML 文档注释

    http://www.cnblogs.com/chenxizhang/archive/2009/07/12/1522058.html 如何:创建 JavaScript XML 文档注释 Visual ...

  3. [Swift通天遁地]七、数据与安全-(8)创建普通PDF文档和加密PDF文档

    ★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★➤微信公众号:山青咏芝(shanqingyongzhi)➤博客园地址:山青咏芝(https://www.cnblogs. ...

  4. MongoDB创建\更新\删除文档操作

     一.插入\创建文档 --当插入一个不存在的文档时,会自己主动创建一个文档 [root@racdb ~]# mongo MongoDB shell version: 2.4.14 connecti ...

  5. Elasticsearch从入门到放弃:文档CRUD要牢记

    在Elasticsearch中,文档(document)是所有可搜索数据的最小单位.它被序列化成JSON存储在Elasticsearch中.每个文档都会有一个唯一ID,这个ID你可以自己指定或者交给E ...

  6. Elasticsearch 使用集群 - 创建和查询文档

    章节 Elasticsearch 基本概念 Elasticsearch 安装 Elasticsearch 使用集群 Elasticsearch 健康检查 Elasticsearch 列出索引 Elas ...

  7. 编写Java程序,使用 dom4j 创建一个 XML 文档,文档名为“city.xml”。注意该文档的格式和数据

    查看本章节 查看作业目录 需求说明: 使用 dom4j 创建一个 XML 文档,文档名为"city.xml".该文档的格式和数据如图所示 实现思路: 创建Java项目,添加dom4 ...

  8. 编写Java程序,创建一个 XML 文档,文档名为“hero.xml”,用于保存“王者荣耀”的英雄信息。

    查看本章节 查看作业目录 需求说明: 创建一个 XML 文档,文档名为"hero.xml",用于保存"王者荣耀"的英雄信息.英雄信息包括编号(id).姓名(na ...

  9. VS2010/MFC编程入门之四十一(文档、视图和框架:分割窗口)

    上一节中鸡啄米讲了文档.视图和框架结构中各对象之间的关系,本节主要讲讲在MFC中如何分割窗口. 分割窗口概述       分割窗口,顾名思义,就是将一个窗口分割成多个窗格,在每个窗格中都包含有视图,或 ...

随机推荐

  1. JDBC学习2:为什么要写Class.forName("XXX")?

    Class.forName(String name) 接上一篇JDBC.本来这个内容是放在前面的一篇里面的一起的,后来发现越写越多,想想看就算了,还是单独开一篇文章好了,这样也能写得更加详细点. 上一 ...

  2. 纠结于搞.Net待遇不高的同学入...

    最近看到不少抱怨搞.net工资低的帖子.别的方向我不是太清楚,作为搞了近8年.Net信息系统开发的码农也想发表下自己的意见. 由于我的阅历和能力有限,首先想限定下本文的范围.这里说的“信息系统”主要包 ...

  3. 我心中的核心组件(可插拔的AOP)~调度组件quartz.net

    回到目录 quartz.net是一个任务调度组件,它可以灵活的设置你的调试方式,按时间,按日期,按周期都可以很容易的实现,quartz不仅可以用在web中,而且还可以部署在winform,winser ...

  4. MVVM架构~使用boxy和knockoutjs实现编辑功能

    返回目录 这个功能我认为非常有用,尤其在后台管理系统中,它对用户来说,使用体验这块非常不错,下面是它的截图

  5. Duplicate id @+id/imageView, already defined earlier in this layout,android

    原文地址http://www.thinksaas.cn/topics/0/448/448554.html 其實這個訊息也是可以解掉的,當然最簡單的解法就是你不要使用相同的id就好了.不過萬一你是幫別人 ...

  6. Atitit 修改密码的功能流程设计 attilax总结

    Atitit 修改密码的功能流程设计 attilax总结 1.1. 注意点1 1.2. 设计修改用户密码功能时把用户ID保存在哪里?1 1.3. Ui设计1 1.4. 功能设计源码1 1.5. Agt ...

  7. atitit 研发管理 要不要自己做引擎自己实现架构?.docx

    atitit 研发管理 要不要自己做引擎自己实现架构?.docx 1.1. 目前已经有很多引擎了,还要自己做吗??1 1.2. 答案是自己做更好,利大于弊1 2. 为什么要自己做??1 2.1. 从历 ...

  8. 快速入门系列--WCF--07传输安全、授权与审核

    这部分主要涉及企业级应用的安全问题,一般来说安全框架主要提供3个典型的安全行为:认证.授权和审核.除了典型的安全问题,对于一个以消息作为通信手段的分布式应用,还需要考虑消息保护(Message Pro ...

  9. Java并发包中CyclicBarrier的工作原理、使用示例

    1. CyclicBarrier的介绍与源码分析 CyclicBarrier 的字面意思是可循环(Cyclic)使用的屏障(Barrier).它要做的事情是,让一组线程到达一个屏障(也可以叫同步点)时 ...

  10. 谈谈主函数main

    我们来看一下主函数 public class HelloWorld{ public static void main(String[] args){ System.out.println(" ...