文档API生成神器SandCastle使用心得
Posted 网络蚂蚁
tags:
篇首语:本文由小常识网(cha138.com)小编为大家整理,主要介绍了文档API生成神器SandCastle使用心得相关的知识,希望对你有一定的参考价值。
一、功能描述
关于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中是否有报错信息,代码是否高亮,链接是否可点。
以上是关于文档API生成神器SandCastle使用心得的主要内容,如果未能解决你的问题,请参考以下文章
如何在 Sandcastle C# 文档构建中链接第三方文档
如何找出导致生成的 Sandcastle 文档存在差异的原因?
Swagger UI教程 API 文档神器 搭配Node使用