在前端开发中，我们经常需要编写和维护文档，特别是在协同开发和代码库较大的情况下，好的文档可以提高开发效率和代码可读性。docgen 是一个 npm 包，可以根据文件中定义的代码元素生成 markdown 格式的文档，本文将介绍如何使用 docgen 生成文档。
安装
使用 npm 安装 docgen：
npm install --save-dev react-docgen
使用
基础用法
首先，需要编写需要编写需要生成文档的代码文件。例如，假设你创建了一个名为 Button.js 的按钮组件，你希望为其生成文档。为了让 docgen 可以正常解析各种注释，需要对代码进行适当的注释：
-- -------------------- ---- ------- --- - ----- ------ - ------------ ------ --------- - -------- ---- -- -- ------- ------- - --------------------- -- -------- ------------- - ----- ---------- - ------ ------ - --------------------------- - -展开代码
注意，在代码注释开头的 @name、@description、@example 等标签是 docgen 规定的。我们可以根据需要自定义更多的标签。
现在，我们就可以运行 docgen 生成文档了。使用以下命令：
./node_modules/.bin/react-docgen Button.js > Button.md
这个命令将 Button.js 文件转化为了 markdown 格式的 Button.md 文档。文档内容如下：
-- -------------------- ---- ------- - ------ ------ --------- --- -------- ---- -- -- ------- ------- -----------------------展开代码
可以看到，docgen 根据注释生成了 markdown 格式的文档，格式清晰，易于跟踪。
docgen 默认只会解析 function 和 class 类型的代码元素，如果需要解析其他类型，例如自定义组件和 props，可以使用 docgen 组件提供的一些工具。
自定义解析器
docgen 支持自定义解析器，以支持更多的代码元素和注释格式。自定义解析器的步骤：
- 安装自定义解析器，例如 react-docgen-typescript。
- 在 .babelrc 或 package.json 中添加编译器插件，例如 babel-plugin-typescript。
- 在文档生成命令中使用新的解析器。
例如，如果我们的按钮组件是使用 TypeScript 编写的，我们可以使用 react-docgen-typescript 作为解析器。首先，在项目中安装 react-docgen-typescript：
npm install --save-dev react-docgen-typescript
然后，在 .babelrc 文件中，添加 babel-plugin-typescript 插件：
{ "presets": ["@babel/preset-env", "@babel/preset-react"], "plugins": ["@babel/plugin-proposal-class-properties", "@babel/plugin-transform-runtime", "babel-plugin-typescript"] }
最后，在文档生成命令中使用 react-docgen-typescript 作为解析器：
./node_modules/.bin/react-docgen-ts Button.tsx > Button.md
docgen 将根据 TypeScript 代码和注释生成新的 markdown 文档。
自定义样式
docgen 生成的 markdown 文档可以定制样式以适应不同的需求。文档样式可以在 CSS 文件中定义。
例如，以下是一个文档样式文件示例：
-- -------------------- ---- ------- --- ------------- - -------- ----- ----------------- -------- ------ ----- - -- - -------------- --- ----- -------- ----------------- -------- -------- ----- ------ -------- - -- - -------- ---- - --- -- ------- ---- - ---- -- ---------- ------- ------------ ----- ------ -------- - --- - ----------------- -------- ---------- ------ - ---- - ------------ -------- ----- -------- ---------- ---------- ------ - -------------- - ---------------- ----- ------- ----- -展开代码
然后，在生成文档命令中指定 CSS 文件：
./node_modules/.bin/react-docgen-ts Button.tsx --styleguideStyles styles.css > Button.md
使用插件
docgen 支持插件，可以用插件合并生成的文档、生成单独的样式文件等等。常用的插件有：
- react-docgen-assert：在编译时检查文档中的示例代码。
- react-docgen-gui：交互式 GUI 工具，支持文档生成和编辑。
- react-docgen-html：生成 HTML 格式的 API 文档。
总结
本文介绍了 npm 包 docgen 的使用方法，包括基础用法、自定义解析器、自定义样式、使用插件等等。docgen 可以帮助我们生成易于阅读的和完善的代码文档，提高代码协作和可读性。
来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/docgen
