前言
polymerts-doc-generator 是一个基于 Polymer 3.x 的自动化文档生成工具。它能够通过分析 Polymer 组件的文档注释以及组件结构自动生成组件的文档页面，并且支持自定义主题风格。在前端开发中，我们经常需要编写文档来记录我们所写的组件，但是手动编写这些文档耗费大量的时间和精力。polymerts-doc-generator 可以解决这个问题，让我们更专注于组件的开发和优化。
该 npm 包适用于有一定前端基础的开发者。本文将介绍该 npm 包的安装和使用，以及一些常用的配置和技巧。
安装和使用
安装
安装该 npm 包的方式非常简单，只需在命令行工具中执行以下命令即可：
npm install polymerts-doc-generator --save-dev
使用
使用该 npm 包生成文档，需要一个配置文件来指导程序在哪些目录下寻找组件，用什么样式生成文档等。在初始化配置文件前，我们先创建一个示例组件用于演示。
示例组件：
-- -------------------- ---- -------
---- ----------------- ---
----
------------ ---- -- - ------ ------- ----------
----- ----------------------
---
----------- ------------------
----------
--------- ----------
-----------
-------------
--------
----- ----------- ------- --------------- -
------ --- ---- -
------ ---------------
-
-
------------------------------------- -------------
---------初始化配置文件
在执行下面的命令前，需要我们在项目的根目录下创建一个 .docgenrc.js 文件来配置生成文档的参数。下面是一个简单的示例：
// .docgenrc.js
module.exports = {
title: 'My Components', // 文档首页的标题
base: 'components', // 生成的文档页面的地址，可以为相对路径或绝对路径
entry: ['src/**/*.html'], // 组件的文件路径，可以为 glob 格式
};其中，title 是文档首页的标题，base 是生成的文档页面的地址，可以为相对路径或绝对路径，entry 是组件的文件路径，可以为 glob 格式。
如果你想要配置更多的参数，可以查看 polymerts-doc-generator 的官方文档。
生成文档
配置文件准备完毕之后，我们可以执行下面的命令来生成文档页面：
npx polymerts-doc-generator --config .docgenrc.js
执行完成之后，在项目的 components 目录下，会生成一个名为 index.html 的文档首页以及对应的组件文档页面。
文档首页会列出所有已找到的组件，并且包含一个搜索框可以搜索组件名称。单击组件名称可以跳转到该组件的文档页面。
文档页面分为两部分，上半部分展示组件的效果，下半部分展示组件的 API。
自定义主题
polymerts-doc-generator 支持自定义主题，我们可以按照自己的需求定制文档页面的样式。在项目的根目录下新建一个名为 themes 的文件夹，并在其中新建一个 my-theme 的文件夹。然后在 my-theme 文件夹中创建一个 index.html 文件，并自定义样式。
.docgenrc.js 文件中加入以下内容，指定自定义主题：
// .docgenrc.js
module.exports = {
// ...
theme: './themes/my-theme/index.html', // 自定义主题
};然后重新执行前面的命令，即可看到自定义主题下的文档页面。
总结
在本文中，我们介绍了 npm 包 polymerts-doc-generator 的安装和使用方法，以及如何进行配置和自定义主题。使用该 npm 包可以帮助我们自动生成组件文档，提高组件开发的效率。希望本文能对你有所帮助。
来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/60056b5681e8991b448e54e7