npm 包 gendocs 使用教程

如果你是一个前端开发者，你可能还需要编写文档来解释你的代码。虽然编写文档是必要的，但是这往往是一项令人厌烦而且耗时的任务。在这种情况下， gendocs 可以成为你的好帮手。

gendocs 是一个自动化生成文档的 npm 包。这篇文章将会向你展示如何使用它来创建一个清晰的文档。

安装

安装 gendocs 可以使用 npm 或者 yarn ，运行下面的命令就可以了。

--- ------- -- -------

或者是

---- ------ --- -------

开始

通过以下命令，我们就可以使用 gendocs 来生成一个默认的文档。

-------

在这个命令运行之后，它会在当前目录下生成一个名为 documentation.md 的文件，这是一个包括了所有的 API 文档的默认文档。

配置

在使用 gendocs 时，你可以通过在工程的根目录中添加一个 gendocs.json 文件来进行配置。

-
  -------- ---- ---------------
  -------- ----------
  --------- ------------------------
  ----------- -----------------------
  ---------- ---------------- ---------
  --------- ----------------
  --------- -
    ---------------------
    -------------------------
    -------------
    ------------
    ---------------
    ----------------
  --
  ---------- ---
  ----------------- ----
-

title

title 是你文档的标题。

style

style 是你的文档的样式， gendocs 支持三种不同的样式： "default", "laravel", "laravel2". 如果没有指定样式，默认情况下 gendocs 会使用 "default" 样式。

output

output 是文档的输出路径。

comments

comments 是指向包含注释的文件或文件夹的路径的数组。 gendocs 将在这些文件或文件夹中搜索注释。

exclude

exclude 的作用是排除在搜索中的特定文件或文件夹，这样它们就不会包含在生成的文档里面。

readme

如果你想在最终生成的文档中包含 README.md 文件的内容，你就应该使用 readme 配置选项。

ignore

ignore 是一个字符串数组，用于指定要从文档中忽略的文件和文件夹的 glob 表达式。这对于排除图片等非代码内容非常有用。

scripts

scripts 是一个对象，其中包含命名为 pre, post, component, package 的属性，它们被用于在生成文档前执行某些任务。

ignoreInternal

如果你想在文档中忽略私有的成员，你可以将 ignoreInternal 设置为 true。

示例

现在，让我们来演示一些 gendocs 的示例代码吧。

注释

使用以下方式来为一个函数添加注释。

---
 - -------
 -
 - ------ -------- ---- - ----
 - ------ -------- ---- - ----
 - -------- -------- -------
 --
-------- --------- ----- -
  ------ ---- - ----
-

最好在代码中添加注释，以便让 gendocs 生成包含 API 文档的文档。

配置文件

gencods 运行需要一个配置文件 gendocs.json。它支持以下配置项

-
  -------- ---- ---------------
  -------- ----------
  --------- ------------------------
  ----------- -----------------------
  ---------- ---------------- ---------
  --------- ----------------
  --------- -
    ---------------------
    -------------------------
    -------------
    ------------
    ---------------
    ----------------
  --
  ---------- ---
  ----------------- ----
-

将上述内容保存为 gendocs.json 文件，放到你的项目根目录下。

运行 gendocs

在你的项目根目录下，运行以下命令，它将根据 gendocs.json 的配置来生成文档。

-------

默认文档

运行 gendocs 命令以后，会在工程目录下生成一个文件 documentation.md，该文件会包含你项目中所有函数和模块的注释。

自定义样式

gendocs 支持自定义样式，并支持三种预置的样式。

------- -- -------

这将生成一个更精美的文档，使用了预置的 laravel 样式。

总结

gendocs 是一个很有用的 npm 包，可以很方便的自动化生成文档。在本文中，我们介绍了如何安装和配置 gendocs、如何添加注释、如何调整样式以及其他一些有用的提示。

来源：JavaScript中文网，转载请联系管理员！本文地址：https://www.javascriptcn.com/post/5eedaa64b5cbfe1ea0610493