之前简单介绍了如何用JSDoc3以及JSDoc3+Docstrap生成jsdoc。
但生成的文档首页Index.html都是一片空白,我们可能需要在这里增加一些说明性的文字。
JSDoc的自定义能力确实很强,我们增加一个readme.md这样的markdown格式的文件就可以了。
比如我的js文件位于:d:\myjs\,要生成的jsdoc放在d:\mydoc。
我们首先可以在任意位置创建一个README.md文件,比如d:\myjs\README.md,文件名是任意的,但扩展名必须是md。
然后以markdown格式编辑该文件,比如:
##概述
这是index.html页面上的介绍
###1. 第一章 hello World
这里介绍如何使用本套类库创建第一个应用
###2. 第二章 扩展你的应用
扒拉扒拉扒拉。。。
然后执行命令:
jsdoc d:\myjs d:\myjs\README.md -t d:\docstrap\template -c d:\docstrap\jsdoc.conf.json -d d:\docstrap_doc
这里md文件必须在命令行里体现出来,即使这个文件跟其它js文件都在一个文件夹中。
贴个效果:
如上图所示,如果想去掉Index那个字样,可以打开Docstrap\publish.js,找到571行(版本不同,可能行数有变化):
generate( 'index', 'Index',
packages.concat(
[
{kind : 'mainpage', readme : opts.readme, longname : (opts.mainpagetitle) ? opts.mainpagetitle : 'Main Page'}
]
).concat( files ),
indexUrl );
将其中的Index字样去掉,就可以了。修改后是:
generate( 'index', '',...................................
关于markdown格式的说明,大家自行搜索一下,很容易找到相关资料。