默认生成的JSDoc3文档只有类和方法的导航。我前面文档提到如何为index.html增加内容描述。
但当我们从导航菜单切换到具体某个类的doc时,再想切换会index首页,默认生成doc中没有这样的能力。
其实JSDoc3现在的版本(3.2.2)确实没有这个功能,但我们可以通过JSDoc3提供的Tutorials功能,折中实现这个功能。
JSDoc3的Tutorials本意是,让使用者提供的文档除了API的doc之外,还可以提供其它的描述文档,比如总体介绍,背景说明,示例文档等等。
我还是以之前文章的搭配为例,JSDoc3+Docstrap。
假设我的js文件位于:d:\myjs\,要生成的jsdoc放在d:\mydoc。在《为JSDoc3的index.html增加说明文档》中,我使用markdown格式创建了一个README.md文件,这里我们可以继续使用到这个文件。
在任意位置创建一个文件夹,假设d:\myjs\Tutorials,文件夹名称也是任意的。把README.md复制到Tutorials文件夹中。
执行dos命令:
jsdoc d:\myjs d:\myjs\README.md -t d:\docstrap\template -c d:\docstrap\jsdoc.conf.json -d d:\docstrap_doc -u d:\myjs\Tutorials
命令执行完毕,我们再打开index.html,会发现上方导航菜单中增加了一项“Tutorials”,点开可以看到里面有一个菜单项“README”。点击README后显示的页面跟index.html还是挺像的,只是没有右侧的纵向导航菜单。但这个基本可以满足用户的需求了。
其实Tutorials目录中放入的所有扩展名为xml,xhtml,html,htm的文件,以及扩展名为md,markdown的文件都会被自动添加到Tutorials菜单中,这样就方便我们写出很多其它文档了。
继续上面的例子,导航菜单中显示的是“README”字样,这样总觉得有点别扭,这是因为JSDoc3默认就是使用文件名作为菜单项。而JSDoc3是支持我们修改菜单标题的。
在上面例子中的Tutorials目录中增加一个README.json文件,在文件中增加内容:
{
"title" : "首页"
}
再重新执行生成命令,我们可以看到“Tutorials”菜单中原来的“README”已经变更为“首页”字样。
我们还可以将Tutorials目录中的文件组织成上下级菜单的形式。下面的例子不是很严谨,大家理解就行。
比如在Tutorials目录中还有a.html,b.html,我们想让a.html,b.html成为“首页”的子菜单。
则修改README.json文件如下:
{
"title" : "首页",
"children" : ["a","b"]
}
再重新执行生成命令,点击Tutorials菜单中的“首页”,在显示的页面中,会看到上面增加了两个链接,a和b。点击a和b,会分别显示a.html和b.html。
理论上,按照同样的方法,a和b也可以继续扩展子菜单,我没有继续尝试。感兴趣的可以自己试试。
另外,看到官方的几个讨论,应该是支持将所有的json配置放在一个文件中的,有兴趣的也可以试试。
讨论:
https://github.com/jsdoc3/jsdoc/issues/332