@bud-fe/docs-gen-cli

一个 node cli 工具，可以扫描指定目录下的所有 .tsx 文件（忽略目录名包含 component 或 components 的目录），解析每个文件顶部约定好的注释内容，并提供相应功能。

🔨 安装

pnpm add @bud-fe/docs-gen-cli -D

🚀 使用

本工具提供了多个命令来帮助您管理和生成文档。

gen-doc

生成页面概览的 Markdown 文档。

npx @bud-fe/docs-gen-cli gen-doc <dir> [output]

• <dir>: (必需) 要扫描的源目录，例如 src/pages。
• [output]: (可选) 生成的 Markdown 文件名。默认为 DOCUMENT.md。

示例:

# 扫描 src/pages 目录并生成 pages-overview.md
npx @bud-fe/docs-gen-cli gen-doc src/pages pages-overview.md

ls-pages

列出所有将被 gen-doc 命令解析的 .tsx 文件，可用于调试和确认文件范围。

npx @bud-fe/docs-gen-cli ls-pages <dir> [options]

• <dir>: (必需) 要扫描的源目录，例如 src/pages。
• [options]: 可选参数。
  • --no-comment: (可选) 查找并列出所有缺少约定头部注释的文件。
  • --no-readme: (可选) 查找并列出所有同级目录缺少 README.md 文件的页面。

示例:

# 列出 src/pages 目录中所有符合条件的文件
npx @bud-fe/docs-gen-cli ls-pages src/pages

# 列出 src/pages 目录中所有缺少头部注释的文件
npx @bud-fe/docs-gen-cli ls-pages src/pages --no-comment

# 列出 src/pages 目录中所有同级目录缺少 README.md 的文件
npx @bud-fe/docs-gen-cli ls-pages src/pages --no-readme

帮助信息

你可以随时使用 --help 选项来查看所有命令或特定命令的帮助信息。

# 查看所有可用命令
$ npx @bud-fe/docs-gen-cli --help

# 查看 gen-doc 命令的详细用法
$ npx @bud-fe/docs-gen-cli gen-doc --help

.tsx 文件头部约定的注释格式

/**
 * 功能模块-页面名称
 * @remarks
 * 这里是该页面的额外说明，支持多行。
 * 第二行说明。
 */