[置顶] API相关工作过往的总结之Sandcastle简要使用介绍

Sandcastle介绍

        在微软推出Sandcastle之前，人们倾向于选择开源的NDoc（.NET代码文档生成器）。NDo可以将 C#.NET 编译生成的程序集和对应的 /doc XML文档，自动转换成如 .NET Framework SDK 类库文档或者 MSDN Library 在线 .NET 类库文档形式的代码文档,然而遗憾的是，这个项目由于资金等问题，作者Kevin于2006年7月宣布不再投入NDoc开源项目的开发，NDoc停留在1.3的历史版本，无法完全支持.NET 2.0，将渐渐淡出人们的视野。

       Sandcastle是一个管理类库的文档编译器，是用于编译发布组件（Assembly）信息的一个工具，这个工具通过反射和Xslt技术，可以从dll文件及其xml注释（命令行编译时加/doc参数或vs2005设置项目属性得到）得到一个完整的帮助文档，格式可以是Html或CHM甚至是任何自定义的格式。

      类库文档形式的代码文档：

Sandcastle生成的输出结果具有以下特点： 

类似于MSDN布局的界面。        

自动生成索引项、内容项目表、主题块和页面布局，提高一致性和熟悉程度。     

自动生成语法宣称部分。

自动生成继承表。     

代码彩色化。    

提供多种风格和语言选择，终端用户可从中选择自己最喜欢的形式。

 

      msdn里有一段英文指引大家使用Sandcastle，有图为证

 

    下载目录：http://www.microsoft.com/en-us/download/details.aspx?id=10526

 

第一步：程序工程设置

 

    生成项目，应注意的是要将项目属性中【生成】选项卡中的XML文档文件选项设置于选中状态，如下图：

 

   项目生成后，在bin\degug目录中生成的文件有与DLL文件同名和一个XML文件，如下图：

  

   编码注意事项：程序代码必须要有标准的XML注释，具体细节本篇里就不详细介绍了。

第二步 使用Sandcastle生成帮助文件

 

1、启动该软件，如下图：

 

2、新建一个项目，参见下图

 

3、选择Add Documentation Source将刚刚创建的类库项目添加到项目中，见下图：

在弹出的对话框中选择BookLib类库项目，如下图：

 

编译项目，等待一段时间后显示编译完成在Sandcastle项目目录中的Help目录下就生成了我们类库的帮助文档，如下图：

 

OK，我们看一下帮助文档的内容吧，下图：