npm 包 auto-readme 使用教程

如今，前端开发从过去的「给页面加效果」，发展到了对于整个网站的构建和设计。除了 HTML、CSS 和 JavaScript 的基础技术，我们还需要关注 npm 包的使用。而在开发 npm 包时，README.md 文件是展示自己的项目的重要手段之一。因此，如何撰写高质量、易懂、详细的 npm 包 README.md 文档，是非常重要的技能之一。

好在有一个集成了自动生成 README.md 文件的命令行工具 —— auto-readme，可以帮助我们快速而准确地编写 npm 包的文档。

auto-readme 是什么？

auto-readme 是基于代码分析的自动生成文档的 npm 包。它通过读取代码和代码注释来分析项目文件，并生成符合标准的 README.md 文件。

auto-readme 能够准确解析代码中的注释，自动收集项目信息。同时，它还能生成代码演示片段、安装流程、使用方法等详细内容。

使用 auto-readme

1. 安装 auto-readme

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

1. 新建 .autoreadme.js 文件

在项目的根目录下，新建一个名为 .autoreadme.js 的文件，并将以下内容复制到文件中：

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

1. 运行 auto-readme

在终端输入以下命令：

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

运行完毕后，就能在 README.md 文件中看到自动生成的文档了。

auto-readme 配置

auto-readme 配置文件 .autoreadme.js 的配置选项如下：

name

Type: string

NPM 包的名称。

dirs

Type: array

需要扫描的目录。

files

Type: array

需要生成输出内容的文件。

ignore

Type: array

忽略扫描的文件或目录。这里的格式与 .gitignore 文件相似。

badge

Type: boolean|object

自动生成的 README.md 文件中，插入一个 badge，用于显示项目的状态信息。

使用布尔值「true」项时，将生成一个默认的 badge，内容包括 package name、version、downloads 和 Travis CI 状态。

使用对象则可自定义 badge 的样式和内容。

例如：

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

description

Type: string

npm 包简短的描述。会在微调案例和代码演示下方显示。

dependencies

Type: object

npm 包依赖的库。

devDependencies

Type: object

npm 包开发依赖的库。

运行命令生成文档效果

auto-readme 生成的 README.md 文件中，包含有安装流程、构建说明、案例展示、代码演示，以及作者等重要信息。

演示效果如下：

-- --

-- --- ---

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

1. 构建说明

• 此 npm 包依赖库：jquery、react；
• 可通过 .xxx() 调用其中的方法；
• 其中的 xxx() 方法用于在页面上展示 xxx 段内容。

1. 案例展示

以下为一些应用该 npm 包的网站：

• 示例站点1 - example.com
• 示例站点2 - example2.com

1. 代码演示

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

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

1. 作者

• 名字：John Doe
• 电子邮件：johndoe@mail.com

© 2021 your package name licensed under the MIT license.

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

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