http://www.cnblogs.com/net515/p/3311584.html

Sandcastle帮助文档生成器使用介绍

一、软件介绍
      Sandcastle是一个管理类库的文档编译器,是用于编译发布组件(Assembly)信息的一个工具,这个工具通过反射和 Xslt技术,可以从dll文件及其xml注释(命令行编译时加/doc参数或vs2005设置项目属性得到)得到一个完整的帮助文档,格式可以是 Html或CHM甚至是任何自定义的格式。
  Sandcastle与.NET Framework 2.0和.NET Compact Framework组合使用。Sandcastle支持本地化,并提供一个基本的命令行编译器界面和一个Visual Studio插件。
  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生成的输出结果具有以下特点: 
Ø         类似于MSDN布局的界面。 
Ø         自动生成索引项、内容项目表、主题块和页面布局,提高一致性和熟悉程度。
Ø         自动生成语法宣称部分。 
Ø         自动生成继承表。 
Ø         代码彩色化。 
Ø         提供多种风格和语言选择,终端用户可从中选择自己最喜欢的形式。 
Ø         输出结果以HTML和CSS形式显示,微软承诺将来提供更多选择。
二、软件使用
  软件的使用方式大致有以下5种:
(1)使用Sandcastle原始的命令行方式
(2)Sandcastle Help File Builder
(3)SandcastleGUI
(4)Sandcastle CHM编译BAT脚本和配置实用工具
(5)DocProject 
 文章以第(2)种为例,介绍Sandcastle的使用
  1、关于生成文档代码注释的规范:
  在源代码文件中,具有规范格式的注释可用于指导工具Sandcastle.msi根据这些注释和它们后面的源代码元素生成 XML。使用这 类语法的注释称为文档注释 (documentation comment)。这些注释后面必须紧跟用户定义类型(如类、委托或接口)或者成员(如字段、 事件、属性或方法)。XML 生成工具称作文档生成器 (documentation generator)。由文档生成器产生的输出称为文档文 件 (documentation file)。文档文件可作为文档查看器 (documentation viewer) 的输入;文档查看器 Sandcastle是用于生成类型信息及其关联文档的某种可视化显示的工具。
  新的代码注释规范需要使用以三个斜杠 (///) 开始注释,这些注释后面必须紧跟它们所注释的用户定义类型(如类、委托或接口)或者成员(如字段、事件、属性或方法).对注释解说需要使用有效的xml标记。
部分标记如下: 
   
2、下载并安装
  --- Sandcastle   http://sandcastle.codeplex.com/   //原始
  --- SHFB(Sandcastle Help File Builder)  http://shfb.codeplex.com/  //文章我们要用到的。
 ①如果之前安装过其它版本,请先卸载后再装。
 ②下载完成后解压,我使用的为SHFBGuidedInstaller_1970版本,得到如下
  
 
打开SandcastleInstaller.exe进入安装界面
 
 
安装相当简单,在连网的环境下,需要的组件会自动提示下载安装。测试时,除了MAML Schema IntelliSense 及MAML Snippet Files选择了跳过没有安装以外,其它全根据提示安装上了。(因为不明白那两个东西是做什么的)。
 
安装完成后,便可以在开始菜单中找到,打开程序,如下
 
 
a.打开软件后首先新建解决方案,注意不要建在桌面等位置,否则生成时会报错。
b.解决方案建成后,在Project Explorer 中右击 Documentation Sources 上右击添加需要生成帮助文档的dll文件。图中①处为我添加的需要生成帮助文档的dll文件
c.底下Content Layout1.content为生成的帮助文档的样式,完全可以不要。
d.选择要生成帮助文档的格式,如图中②处,我要生成html格式的帮助文档。
e.其它设置默认即可,过会底下会做介绍。
f.点击③处开始生成,如图
 
g.生成完成后,会看到提示:
Build completed successfully at 09-09-2013 11:47 下午.  Total time: 00:01:11.3906
即可在Sandcastle解决方案目录下看到Help文件夹,即是生成的帮助文件。
 
h.如果不能编译生成CHM文档或者生成CHM时报错,则需要安装HTML Help Workshop(需要用到其中的hhc.exe文件)
 
3、集成到Visual Studio中
  a.回到Sandcastle安装程序目录 ,打开 InstallResources文件夹,看到以下三个文件
双击最下边的vsix文件,反应一会儿会弹出如下错误,即表示安装成功了:
 
b.现在在解决方案中添加项目,如下
c.选择Documentation-->Sandcastle Help File Builder Project-->确定
d.双击Project Properties 可以设置项目的属性
属性个性化定制主要属性有:
   1.生成属性设置,如需要生成什么类型的文档(可选chm、网站站点等)
   2.文档内容属性设置,如对命名空间的解说。(命名空间在C#代码中是不可以有注释的,故在此可以设置,也可以在项目中新建一个类NamespaceDoc.cs其代码为:
1 namespace  TestForHelp
2 {
3 ///<summary>
4 ///These are the namespace comments for New <c>TestForHelp</c>
5 ///</summary>
6 [System.Runtime.CompilerServices.CompilerGeneratedAttribute()]
7 classNamespaceDoc
8 { }
9 }
   3.文档文件的属性设置:如页眉、页脚、版权信息。
e.同样,右击 Documentation Sources 上右击添加需要生成帮助文档的dll文件,可一次添加多个
f.在项目名上(如DocumentationHelp)右击,添加--新建项,可指定项目模板
 
g.所有设置完成后,生成项目,即可得到想要的帮助文档,同样保存在项目下Help文件夹下。
h.再次提醒,如果不能编译生成CHM文档或者生成CHM时报错,则需要安装HTML Help Workshop(需要用到其中的hhc.exe文件)
 参考资料:
 3.使用
Sandcastle 生成 chm 帮助文档
 (使用Sandcastle原始的命令行方式)
 4.软件的帮助文档,讲得很全,但全是英文。

Sandcastle生成帮助文档的更多相关文章

  1. 生成chm文档工具- Sandcastle -摘自网络

    Sandcastle是微软官方的文档生成工具,NDoc开发停止后,这个貌似也是唯一的一个这方面的工具.它从dll文件及其xml注释文件能够 生成完整的帮助文档,支持多种生成格式(Helpe1x:chm ...

  2. 使用Sandcastle 基于代码注释生成接口文档

    一. 工具下载: 1. Sandcastle:Sandcastle是微软官方的文档生成工具,下载地址:http://www.codeplex.com/Sandcastle 2. SHFBGuidedI ...

  3. .Net魔法堂:提取注释生成API文档

    一.前言 在多人协作的项目中,除了良好的代码规范外,完整的API文档也相当重要.通过文档我们快速了解系统各模块的实际接口,及其使用场景.使用示例,一定程度上降低沟通成本,和减少后期维护中知识遗失等风险 ...

  4. 自动生成api文档

    vs2010代码注释自动生成api文档 最近做了一些接口,提供其他人调用,要写个api文档,可是我想代码注释已经写了说明,能不能直接把代码注释生成api?于是找到以下方法 环境:vs2010 先下载安 ...

  5. .net 提取注释生成API文档 帮助文档

    提取注释生成API文档   一.前言 在多人协作的项目中,除了良好的代码规范外,完整的API文档也相当重要.通过文档我们快速了解系统各模块的实际接口,及其使用场景.使用示例,一定程度上降低沟通成本,和 ...

  6. 注释生成Api文档

    1.开发背景 最近一直在写dubbo接口,以前总是用word文档写接口描述然后发给别人.现在太多了,而且跟别人对接联调的人家急着用,根本没时间去写word文档.那就想想怎么用doc文档注释自动生成接口 ...

  7. [.NET] WebApi 生成帮助文档及顺便自动创建简单的测试工具

    ==========最终的效果图========== ==========下面开始干活:生成帮助文档========== 一.创建 WebApi 项目 二.找到 HelpPageConfig.cs 并 ...

  8. Aspose.Words简单生成word文档

    Aspose.Words简单生成word文档 Aspose.Words.Document doc = new Aspose.Words.Document(); Aspose.Words.Documen ...

  9. 利用Java动态生成 PDF 文档

    利用Java动态生成 PDF 文档,则需要开源的API.首先我们先想象需求,在企业应用中,客户会提出一些复杂的需求,比如会针对具体的业务,构建比较典型的具备文档性质的内容,一般会导出PDF进行存档.那 ...

随机推荐

  1. windows时间函数

    介绍        我们在衡量一个函数运行时间,或者判断一个算法的时间效率,或者在程序中我们需要一个定时器,定时执 行一个特定的操作,比如在多媒体中,比如在游戏中等,都会用到时间函数.还比如我们通过记 ...

  2. 第二章排错的工具:调试器Windbg(上)

    感谢博主 http://book.51cto.com/art/200711/59731.htm <Windows用户态程序高效排错>第二章主要介绍用户态调试相关的知识和工具.本文主要讲了排 ...

  3. ie浏览器提交参数和其它浏览器的区别

    场景描述: 用户注册模块(ajax提交方式,post方法),在url后追加了一个参数,如:url+‘btnvalue=中文参数’,如此在非ie浏览器注册时,功能完好,但在ie下注册不成功.调式后发现在 ...

  4. 【图像处理】Bilinear Image Scaling

    Bilinear image scaling is about the same as nearest neighbor image scaling except with interpolation ...

  5. LeetCode My Solution: Minimum Depth of Binary Tree

    Minimum Depth of Binary Tree Total Accepted: 24760 Total Submissions: 83665My Submissions Given a bi ...

  6. jQuery 顶部导航尾随滚动,固定浮动在顶部

    jQuery 顶部导航尾随滚动.固定浮动在顶部 演示 XML/HTML Code <section> <article class="left"> < ...

  7. 利用objc的runtime来定位次线程中unrecognized selector sent to instance的问题

    昨天遇到一个仅仅有一行错误信息的问题: -[NSNull objectForKey:]: unrecognized selector sent to instance 0x537e068 因为这个问题 ...

  8. solr4.9r+ Eclipse 4.3+ tomcat 7.5 +winds7(二)

    尊重原创,原文地址:http://blog.csdn.net/chunlei_zhang/article/details/38778945 这另外一种方法是将solr项目部署到tomcat上,执行to ...

  9. c# winform 子窗体访问父窗体中的方法和变量

    今天的工作中突然用到这个了,不过以前没有接触过呢!不过,在有经验的同事的帮助下,这个问题也很快解决了.具体可以分为以下几种方式: 1.在父窗体中构造子窗体对象时,将父窗体传递过去: 如:FrmSub ...

  10. android File文件的读写操作

    本程序实现两个文本框和两个按钮,其中一个文本框和一个按钮用于读取文件内容.另一个文本框和另一个按钮用于写入. java代码: package com.example.activity; import ...