SHFB 全称 Sandcastle Help File Builder ,项目地址:https://github.com/EWSoftware/SHFB。 它使用代码中的xml注释生成说明文档。因此,使用SHFB之前要给代码编写好xml注释。
安装
进入项目的 Github Release 页面:https://github.com/EWSoftware/SHFB/releases 下载最新发行版本,SHFBInstaller_2023.7.8.0.zip
下载完成后解压,里面有一个安装器,双击打开
根据提示,安装必需的组件即可,我只安装了这个一个组件:
然后按 Next 到最后一页,按右下角 Close 按钮即安装完成。
使用
打开安装文件夹,找到 SandcastleBuilderGUI.exe ,打开这个程序。
1.新建 SHFB 项目
左上角 File>New Project
SHFB项目文件的后缀为.shfbproj
2.选择 .NET 框架版本
3.在 Visual Studio 中生成 xml 文件
右键项目,打开项目属性,在生成>输出中勾选生成文档文件
然后生成一下项目,xml文件就一起生成了:
4.向 SHFB 项目添加源文件
这一步是把上一步生成的 dll 和 xml 文件添加到 SHFB 项目。右侧 Project Explorer>(项目名)>Documentation Sources,右键 Add Documentation Sources,选择源文件。找到生成的dll、xml文件,并添加。
5.项目属性
- 帮助文件设置为中文
设置为中文后生成的html文件格式有bug,我向项目提了 issue ,最新版已经修复。
-
首页显示所有命名空间
-
visibility 生成哪些成员的说明文档
-
Missing Tags 生成的说明文档包含哪些xml注释标签。例如,c#代码注释里面没有写
<returns>
标签的值,就勾选掉这一项
6.生成帮助文件(说明文档)
点击顶部Build按钮,构建帮助文件:
生成的帮助文件,在SHFB项目文件的同一级的Help文件夹内,我生成的是网页,所以,直接打开index.html
,就是帮助文件。
随机展示一个页面: