简介
@ckeditor/jsdoc-plugins 是 CKEditor 团队推出的一个 npm 包，可以用于自动生成 API 文档页面。它基于 JSDoc 标记生成 Markdown 文档，并提供了丰富的配置选项，可以根据项目需要自定义生成的文档风格和内容。
本文将介绍如何使用 @ckeditor/jsdoc-plugins 生成 API 文档页面，并提供示例代码和配置选项的详细解释。
安装
首先，需要安装 @ckeditor/jsdoc-plugins：
npm install @ckeditor/jsdoc-plugins
安装完成后，就可以使用其中的命令行工具了。
使用方式
使用 @ckeditor/jsdoc-plugins 主要需要编写配置文件和 Markdown 模版文件。这两个文件都可以放在项目的根目录下，或者单独存放在一个目录下。
配置文件
下面是一个较为完整的配置文件示例：
-- -------------------- ---- -------
-
--------- -
---------- -
-------
--
---------- -
----------------
--
----------------- -------------------
----------------- ---------------
--
------- -
-------------- ---------
---------- -----
----------- -----------------------------------------------------------
--
---------- -
------------------
--
----------- -
--------- ---------
----------- ----
--
------------ -
-------------- -----
----------------- -----
---------- -
-------------------- ----
--
------------- -
------- --- ---------
-------------- ----- -- - ---- ----------
------- ----------------------------------
----------- -
-
------- -------
------- -----------------------------
--
-
------- -------
------- -----------------------------
--
-
------- ---------
------- -------------------------------
-
-
-
-
-配置文件中的各个选项含义如下：
source.include：需要编译的文件路径，可以是一个数组。下面两个选项分别指定了需要编译的文件和需要排除的文件。opts.destination：编译生成的 Markdown 文件和 HTML 文件存放的位置。opts.template：编译使用的模版文件路径。plugins：插件列表。在本示例中只使用了markdown插件。markdown：Markdown 配置，这里将默认的解析器设置为marked并启用了自动断行。templates：模版配置，在这里配置生成的文档页面的各种属性，如页面标题、导航栏链接等。
Markdown 模版文件
Markdown 模版文件用于设置 API 文档页面的外层结构。@ckeditor/jsdoc-plugins 提供了一些模版文件供使用，也可以自己编写。
在本文中使用了默认的模版文件。
命令行
使用命令行工具，执行以下命令即可生成 API 文档页面：
jsdoc -c path/to/config.js
以上命令中，-c 参数指定了使用的配置文件的路径，即 path/to/config.js。
示例代码
假设有以下代码文件：
-- -------------------- ---- ------- --- - --- --- -------- - ------ -------- - - ------ -------- - - -------- -------- -- -------- ------ -- - ------ - - -- -
在 ./src/add.js 下，可以使用以下配置文件：
-- -------------------- ---- -------
-
--------- -
---------- -
--------------
-
--
------- -
-------------- --------
--
------------ -
-------------- -----
----------------- -----
------- --- ---------
-------------- ----- -- - ---- ----------
------- ----------------------------------
----------- -
-
------- -------
------- -----------------------------
--
-
------- -------
------- -----------------------------
--
-
------- ---------
------- -------------------------------
-
-
-
-生成的 API 文档页面如下：
-- -------------------- ---- ------- - -- ------- ---- -- - ---- -------- -- --------- ---- ------ ------------------ ------ - ------------------------ ---------- --- ------------ ----- ----- -- --------- --- ------ -- - ------------------- --- --- -------- - ----- - ---- - - --- - --- - - - - ------------------- - - - - ------------------- -
结论
@ckeditor/jsdoc-plugins 可以方便地生成 API 文档页面，并且提供了丰富的配置选项，可以根据项目需要进行自定义。同时，它也可以与其他工具集成使用，例如使用 Git Hooks 在代码提交前自动生成 API 文档页面。我们建议在项目中使用该工具，以方便维护和开发。
来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/ckeditor-jsdoc-plugins