在前端开发中，文档是不可或缺的一部分。而对于开源项目或者团队合作中的代码文档管理，往往需要使用 jsdoc 来生成文档。但是，使用 jsdoc 需要一定的学习成本和配置过程，而且文档生成效果也不太令人满意。因此，在这里介绍一款 npm 包 —— jsdoc-oblivion，它可以让你更方便地生成文档，并且生成的文档效果也更加优美。
什么是 jsdoc-oblivion
jsdoc-oblivion 是一个使用简单、功能强大、支持主题自定义的 JSDoc 文档生成器，它可以基于 jsdoc 提供的注释为 JavaScript 代码自动生成 API 文档，并使用一套自定义的主题进行渲染和展示。
开始使用 jsdoc-oblivion
1. 安装 jsdoc-oblivion
在命令行中执行以下命令即可安装 jsdoc-oblivion：
--- ------- -------------- ----------
2. 添加 JSDoc 注释
在需要生成文档的 JavaScript 文件的函数和类的开头添加 JSDoc 注释，例如：
--- - ------- - - -------- - - -- ------- - - ------ --- - - ------ -------- ---- - ------ - ------ -------- ---- - ------ - -------- -------- ------- -- -------- --------- ----- - ------ ---- - ----- -
3. 配置 jsdoc-oblivion
首先，在你的项目根目录下创建一个 jsdoc-oblivion.json 文件，并添加以下配置：
-
--------- -
----------------- -------------------
----------------- ---------------
--
---------- ---------------------
------- -
---------- -----
-------------- --------
--
------------ -
---------- -
-------------------- ----
--
------- -----------------------------------------------
-
-其中，source 属性表示扫描哪些文件来生成文档；plugins 属性表示使用了哪些插件；opts 属性表示文档输出的位置等信息；templates 属性表示使用哪个主题。
4. 生成文档
在命令行中执行以下命令来生成文档：
------------------------- -- -------------------
其中，-c 表示指定配置文件。
生成的文档默认存储在指定的目录下，可以在浏览器中打开 index.html 文件来查看文档效果。
定制化 jsdoc-oblivion 主题
如果你觉得默认主题不太符合你的需求，你也可以按照自己的喜好定制化 jsdoc-oblivion 主题。下面是一个简单的定制化示例：
首先，复制 default 主题到你的项目根目录下的 templates 文件夹内。
在 templates 文件夹下创建新的文件夹，例如 custom，作为你新定义主题的目录。创建一个名为 layout.tmpl 的模板文件，在里面添加以下代码：
--------- -----
----- ----------
------
----- ----------------
---------- ----- ----------
----- ---------------- -------------------------- ----------------
-------
------
---- -------------
--------
------- ----- -------
-----
----
-- ------- - - -- - - ------------------ - - -- ---- - ---
------ --------- ----------------- ------- ------------------- -----------
-- - ---
-----
------
---------
---------
--- -------- --
----------
--------
-- ---------- - ---
--- ------ --
-- - ---
---------
------
-------
-------这个文件定义了新主题的基础布局，如文档的标题、导航栏、主体内容等。
接着，创建一个名为 symbols.tmpl 的模板文件，在里面添加以下代码：
-- --- ------- - ------ ----- ------- --- -- ---- -- -------------------------------- - --- ------ --------- --------------- ------------ ----------- ----------- -- --- --- -----
这个文件定义了文档的左侧导航栏，显示了文档中所有的类名。
最后，不要忘记在 jsdoc-oblivion.json 文件中添加以下内容：
------------ -
--------- -
------------- -------------------------------
----------- -
---------- -------------------------------
-
-
-其中，layoutFile 表示使用自定义的 layout.tmpl 文件，partials 表示使用自定义的 symbols.tmpl 文件作为左侧导航栏。
到此为止，你已经成功定制化了一个 jsdoc-oblivion 主题。
结语
jsdoc-oblivion 是一个非常好用的文档生成工具，支持定制化主题，生成的文档效果也非常优美。它让我们在代码注释的基础上更高效、更自然地生成文档，让整个项目更加规范和易于维护。希望这篇文章可以让你更好地了解和使用它。
来源：JavaScript中文网 ，转载请联系管理员！ 本文地址：https://www.javascriptcn.com/post/68280