初试SHFB全记录

    学无止境 ImbaQ 1742次浏览 0个评论

    “得文档者得天下”记得这是在某个提问:“XXX组件为什么使用的人比较少”中有个让我过目不忘的回答。

    其实很多时候第三方库、控件、平台之类的相当优秀,但总少一个优秀的使用文档,第一是给人的感觉不那么专业,其次对于开发者自己觉得非常简单的东西别人第一感觉总是陌生的。

    一直都好奇chm和网页版msdn是怎么做出来了,就借着给iHomeSoft.Helper做文档的机会来学习记录下整个过程还有遇到的吭!

    问过度娘生成chm的工具曾经有ndoc,但现在就 Sandcastle Help File Builder 一家独大了,居然没得选那就下载安装吧,安装过程略过。。。

    安装后有两种使用方式:自带的gui工具、直接在vs中建立相应的项目。

    初试SHFB全记录

    1、gui工具第一步:添加dll和对应xml,选择需要生成的格式

    初试SHFB全记录

    2、基本信息选项,按需填写即可。

    3、后面的详细选项粗略看了一遍暂时没有需求,都按默认即可,若需具体设置可参考这里

    4、然后就可以build了,生成成功后会项目文件的同级目录下生成help目录:

    初试SHFB全记录

    chm是单独离线版的帮助文档,其它是在线版的。


    在生成过程中遇到的大坑:

    SHFB(0,0): warning BE0060: The file path ‘D:\iHomeSoft\develop\iHomeSoft.Helper\iHomeSoft.Helper\CHM_Build\Help\Working\Output\HtmlHelp1\’ contains a comma or ‘.h’ which may cause the Help 1 compiler to fail.

    HHC3004

    SHFB(0,0): error BE0043: Unexpected error detected in last build step.  See build log for details.

    一直报这个错误,百度未果,才硬着头皮去啃官方文档:

    初试SHFB全记录

    简直清晰明了啊,文件夹路径不能有类似   .help 的,这又是一个好文档的范例啊。


    chm生成好,我还需要把html版的部署起来:

    单独建立文件夹,上传文件,配置伪静态,OK。可以访问了,然而发现搜索功能不能用,始终返回查找不到结果,开发者工具祭出分析下:

    初试SHFB全记录

    第一感觉aspx和php两个页面影响不大,因为本地测试没有任何服务器环境时候搜索功能是正常,所以 search.html 页面应该就能完成搜索了,那么问题应该处在两个json上了,没什么好说,文件存在,路径正确,伪静态没问题,依然是404,那么mime的锅吧。服务器上添加:

    文件扩展名:”.json”

    MIME类型:”application/x-javascript”

    再次刷新,大功告成:

    初试SHFB全记录

    整体效果还是不错的,完整页面功能:戳我


    iHomeSoft, 版权所有丨如未注明 , 均为原创丨本网站采用BY-NC-SA协议进行授权 , 转载请注明!
    初试SHFB全记录