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

Posted 2020-12-27 网络蚂蚁

一、功能描述

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

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

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

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

二、下载与安装

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

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

三、配置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.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 的报错信息，点击取消复选框，哪个节点的报错就不会报错。

　　

五、SandCastle在vs中的使用

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

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

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

　　

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

　　

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

　　

六、运行生成API

　　上面所有步骤完成之后就可以运行sandcastle了，点击build the help file生成

　　

　　生成成功之后在当前生成目录下，查看生成文件是否齐全，如果文件不全，那么原因在于生成不成功或配置不正确

　　

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