文档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 生成代码帮助文档

如何在 Sandcastle C# 文档构建中链接第三方文档

如何找出导致生成的 Sandcastle 文档存在差异的原因?

Swagger UI教程 API 文档神器 搭配Node使用

一个无需注解的 SpringBoot API文档生成神器,相当哇塞!

再见丑陋的 SwaggerUI,这款开源的API文档生成神器界面更炫酷,逼格更高!