文档API生成神器SandCastle使用心得

1、功能描述

　　关于Sandcastle网上的参考资料相对较少，Google出来不少资料都是全英文的，相对于我这种英语渣渣看起来仍是很费劲的。

　　言简意赅，Sandcastle主要功能是可以将C#类生成相似MSDN风格帮助文档的工具，支持本地化，并提供一个基本的命令行编译器界面和一个Visual Studio插件。
优势：

　　1.生成简单，工做量小，几分钟以内就能完成一个项目的api文档制做。
　　2.自动生成索引项、内容项目表、主题块和页面布局，提升一致性和熟悉程度。
　　3.代码高亮，易读性强
　　4.生成api界面美观。
缺点：

　　只支持visual studio,意思是只支持微软旗下产品。

2、下载与安装

　　我是在github中下载的sandcastle，连接隧道 https://github.com/EWSoftware/SHFB/releases，下载时需注意版本号，我没有看版本备注就直接下载了最新版本的sandcastle，安装后生成api后直接报错了，不能生成成功。后来排查后发现是版本问题，个人idea是vs2013,当前sandcastle版本只支持最低vs2015的Idea,因此一直报错。

这个版本中备注描述的很清楚，这是最后一个支持vs2013的版本。

3、配置SandCastle

　　主要配置详解

3.1 首先打开SandCastle，新建一个文件用来存放sandcastle新建的工程文件，相似vs中新建项目后的解决方案。

3.2 在项目属性中选择须要生成的api类型，若是你想生成相似MSDN帮助文档风格，就能够选择Website。

3.3 Framework version 选择生成解决方案的framework版本号，若是与之不一致，则生成api时会报错

　　chm类型生成的文档（参考）

　　 website类型

　　在vs中的引用类按f1可打开该类的帮助文档。

3.4.点击Project Explorer，点击新建的api文件，右击Documentation Sources选择Add Document Source

　　

3.5 选择的类库生成属性中需在输出中xml文档文件复选框打钩在生成，不然生成api无效。

3.6 选择所需生成的类库，也就是后缀名为.csproj的文件便可

4、常见错误

4.1 SHFB: Error BE0043: Unexpected error detected in last build step.  See output above for details.

　　错误信息的意思是缺乏程序集的引用，那我就须要把不用的程序集剔除掉，那么如何剔除呢，请看一下操做

　　

　　

4.2 SHFB: Error BE0064: BUILD CANCELLED BY USER

　　这个错误是因为框架版本不一致所引发的，也就是若是该项目生成时选择的framework版本为4.5，而sandcastle配置的是4.0版本，那么就会报错。

4.3 Sandcastle [丢失<summary> 节点]的问题

　　遇到这个问题，首先查看代码注释是否有<summary>节点，是否规范。

　　

　　而后有人会说我明明在代码中已经定义了summary 节点，为何还会报这种错呢？

　　这种我尝试最暴力的方法就是让它不提示这个错误，在sandcastle中设置missing tags，取消<summary> elments 的报错信息，点击取消复选框，哪一个节点的报错就不会报错。

　　

5、SandCastle在vs中的使用

　　前面说了都是sandcastle软件的独立使用，还有一种方法是将其集成在vs中使用，使用方法与独立使用相差不大。

       若是是已经安装了sandcastle，那么请忽略如下安装步骤。

       5.1 在sandcastle目录文件夹下找到后缀为vsix的插件，双击执行，若是弹出此扩展已安装，那么表示安装成功

　　

5.2 在需生成api的项目下添加项目，若是已安装成功，那么在已安装的扩展插件中Documentation就会出现sandcastle插件，输入名称，存放位置，点击肯定添加。

　　

　　5.3.添加完成后，此时的操做和不是集成在vs中的无明显差异，如需生成文档，右击新建的文件，点击生成便可。

　　

6、运行生成API

　　上面全部步骤完成以后就能够运行sandcastle了，点击build the help file生成

　　

　　生成成功以后在当前生成目录下，查看生成文件是否齐全，若是文件不全，那么缘由在于生成不成功或配置不正确

　　

　　双击index.html查看api中是否有报错信息，代码是否高亮，连接是否可点。