制作API离线chm帮助文件教程

 

 当我们开发好一个通信库的时候，我们希望给这个通信库配备一个帮助文档，最好的方式，就是有一个离线的chm版本的API文档，这样别人在使用的时候，就可以清楚看到命名空间、类的结构，同时也能看到每个方法和属性的结构。
刚好最近在制作xktComm通信库的API帮助文档，借此机会，跟大家介绍一下如何制作API文档。
1、首先要将制作的dll写好注释，在类库项目属性中，勾选XML文档文件，这样就会生成该dll对应的说明文档xml文件。

 

 2、然后需要下载一个软件SHFB，下载地址在github上：https://github.com/EWSoftware/SHFB/releases

 

 选择最新版下载即可。
如果github访问不了，可以通过公众号【dotNet工控上位机】获取，回复关键词：API制作套装
获取到的SHFB软件目录如下所示：

 

 3、打开InstallResources文件夹，找到SandcastleHelpFileBuilder.msi，双击安装，安装过程很简单，一路Next即可。

 

 4、安装完成后，在跳到InstallResources文件夹同级目录，找到SandcastleInstaller.exe，双击安装。

 

 5、安装过程会弹出两次下图的提示框，点击是，继续到下一步。

 

 6、安装完成后，在开始菜单中的最近添加中，找到Sandcastle Help File Builder GUI，点击打开。

 

 7、打开之后，如果出现下面的错误提示，说明需要安装一个插件——BuildTools，获取方式，在前面获取的API制作套装中，有一个名称为BuildTools_Full.exe的程序，双击安装，如果没有错误，这一步跳过即可。

 

 8、成功打开后，新建一个项目，名称自己定义，添加第一步中准备好的dll及其对应的xml文档。
9、然后通过左侧的向导进行一些相关的设置，首先是Build页面，主要设置文档生成类型、语言及框架版本。

 

 10、切换到第二栏Help File，设置相关的Title、版本号及相关版权信息。

 

 11、点击Documentation下的Build Project按钮，生成项目。
12、如果出现下图错误，错误代码BE0037，需要安装一个插件——htmlhelp，对应的安装包已经放到API制作套装中，获取方式，公众号后台回复：API制作套装。

 

 13、安装完成后，重新Build Project，如果仍然出现错误，错误代码BE0065，需要再安装一个插件——vs_buildtools，对应的安装包已经放到API制作套装中，获取方式，公众号后台回复：API制作套装。

 

 14、不出意外的话，应该可以生成，生成结果如下：

 

 15、这样我们就生成了一个API的帮助文档，我们可以对照Log，看看有哪些警告，因为可能有一些地方我们的注释并不完整。
16、有个地方值得注意，当我们将所有的方法和类都添加注释后，我们生成的时候，可能还会有警告，大致意思是命名空间并没有注释，命名空间的注释在代码里是添加不了的，需要在Sandcastle Help File Builder GUI软件中添加，点击左侧导航栏的Summaries，点击Edit Namespace Summaries，进入界面后，通过点击选择命名空间，右击一下，就可以输入所选命名空间的注释说明，全部输入完成后，点击Close即可。

 

 16、下面是最终生成的chm帮助文档。【图片有误，后台回复API，查看完整版】