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文件）

参考资料：

1.使用Sandcastle帮助文档生成流程

2.利用SandCastle生成帮助文档

3.使用 Sandcastle 生成 chm 帮助文档 (使用Sandcastle原始的命令行方式)

4.软件的帮助文档，讲得很全，但全是英文。

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

Sandcastle帮助文档生成器使用介绍相关推荐

JSDoc --JS API文档生成器
JSDoc 是一个JavaScript的API文档生成器. 他可以让开发者在开发的过程中, 将编写的注释通过JSDoc工具生成一个api文档, 妈妈再也不用担心我不会写接口文档了. 这里是原作者Git ...
Javadoc （Java API 文档生成器）详解 [Javadoc 概述][Javadoc 标签][Javadoc 命令][Javadoc 生成 API 文档]
您的"关注"和"点赞",是认可,是支持,是动力. 如意见相佐,可留言. 本人必将竭尽全力试图做到准确和全面,终其一生进行修改补充更新. 文章目录 1 Javad ...
Jazzy 文档生成器使用
Jazzy 文档生成器使用 Jazzy 简介 jazzy 是一个命令行实用程序,可以为 Swift 或者 Objective-C 生成文档,输出风格和官方文档匹配(也可以自定义模板) 如果是 Swif ...
simple css 汉化,Simple CSS(CSS文档生成器)
Simple CSS(CSS文档生成器)简介 Simple CSS(CSS文档生成器)简介一:Simple CSS是一款CSS文档生成器,帮助网页开发人员快速生成CSS样式,Simple CSS使用非 ...
开源数据库表结构文档生成器
大家好,我是TJ 一个励志推荐10000款开源项目与工具的程序员 TJ君前几天和一个在银行科技部上班的同学聚会,同学跟TJ君吐槽,一些小银行的科技表面看上去专业,实际各种马虎不负责. 打个比方,有一次 ...
源代码文档生成 Doxygen介绍(转载)
源代码文档生成 Doxygen介绍(转载) 收藏 Doxygen介绍一.Doxygen介绍在项目开发过程中最重要的是如何和团队中其它成员沟通,如何在项目完成后减低维护成本,随着公司的人员流动,怎样 ...
python文档生成工具_pydoc --- 文档生成器和在线帮助系统 — Python 3.9.1rc1 文档
pydoc --- 文档生成器和在线帮助系统¶ The pydoc module automatically generates documentation from Python modules. ...
文档中没有介绍的SQL Server DBCC命令
文档中没有介绍的SQL Server DBCC命令 http://www.searchdatabase.com.cn/showcontent_11822.htm http://www.searchda ...
文档理解最新技术介绍 | DAS 2020 Keynote Speech
DAS 2020 (Document Analysis System,文档分析系统研讨会) 于 7月26-29日在武汉召开,本次研讨会中有不少精彩的内容,昨天向大家推荐了来自华南理工大学金连文老师和 ...

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

Sandcastle帮助文档生成器使用介绍相关推荐

最新文章

热门文章