文档静态站点开发工具【免费下载链接】docz✍ It has never been so easy to document your things!项目地址https://gitcode.com/gh_mirrors/do/docz点击查看免费下载本指南以 docz 仓库中的examples/monorepo-separate-docs示例为核心讲解如何在 monorepo 中用一个独立的docs包仅包含mdx与 docz 相关配置去文档化其他 peer 包中的组件。读完本文你将掌握docgenConfig.searchPath与filterComponents的底层运行机制、JavaScript/TypeScript 双版本组件的文档生成方法以及 dev/build/serve 的完整工作流。示例全景一个文档包文档化两个 peer 包examples/monorepo-separate-docs是一个使用 Lerna Yarn Workspaces 组织的 monorepo其顶层结构为packages/alert基于prop-types的 JavaScript 版Alert组件包packages/alert-ts基于 TypeScript 类型注解的Alert组件包通过 microbundle 构建packages/docs独立的 docz 文档包仅依赖mdx与 docz负责为前两个包生成文档。根目录的 package.json 声明了 workspaces 与代理脚本lerna.json 则配置packages/*作为包管理范围。根包把文档相关的三个命令直接转发给packages/docs{ scripts: { build: cd packages/docs yarn run build, dev: cd packages/docs yarn run dev, serve: cd packages/docs yarn run serve }, devDependencies: { lerna: ^3.16.4 } }也就是说你可以在 monorepo 根目录统一执行yarn dev/yarn build/yarn servedocz 实际运行在packages/docs这个文档专用包内。这种“文档与业务代码分离”的组织方式特别适合多包仓库中由专人维护文档、且不希望文档目录污染各业务包的情况。快速开始初始化、安装与运行方式一通过脚手架创建你可以直接用create-docz-app拉取该示例--example monorepo-separate-docsnpx create-docz-app docz-app-monorepo-separate-docs --example monorepo-separate-docs # 或 yarn create docz-app docz-app-monorepo-separate-docs --example monorepo-separate-docs方式二手动下载示例curl https://codeload.github.com/doczjs/docz/tar.gz/main | tar -xz --strip2 docz-main/examples/monorepo-separate-docs mv monorepo-separate-docs docz-monorepo-separate-docs-example cd docz-monorepo-separate-docs-example安装依赖文档包 README 给出了依赖安装命令yarn # npm i四个核心命令文档包在 package.json 中声明了三个脚本配合根包转发整条工作流如下阶段命令文档包内命令monorepo 根目录作用安装依赖yarn/npm iyarn安装全部 workspace 依赖开发预览yarn dev/npm run devyarn dev启动 docz dev server带热更新静态构建yarn build/npm run buildyarn build生成可部署的静态站点预览产物yarn serve/npm run serveyarn serve在本地预览 build 产物其中dev对应docz devbuild对应docz buildserve对应docz serve这三个命令的实现在 core/docz-core/src/commands 中。关键配置让 docz 跨包发现组件让packages/docs能文档化packages/alert与packages/alert-ts的秘密全在文档包的 doczrc.jsexport default { typescript: true, docgenConfig: { searchPath: ../, }, filterComponents: files { return files.filter( filepath /\/[A-Z]\w*\.(js|jsx|ts|tsx)$/.test(filepath) || filepath.includes(/alert/index.js) || filepath.includes(/alert-ts/src/index.tsx) ) }, }docgenConfig.searchPath把组件搜索范围扩展到整个 monorepo默认情况下docz 只在文档包的src目录配置项src默认./内搜索组件并生成 props 元数据。而本示例将searchPath设置为../即从文档包向上回溯到 monorepo 根目录从而把packages/下的所有源码纳入 docgen 的扫描范围。从源码看这一行为由 core/docz-core/src/states/props.ts 中的getPattern函数实现若配置了docgenConfig.searchPatterns则直接使用自定义 glob 模式否则取docgenConfig.searchPath未配置时回退到src即source最终基于path.resolve(root, searchPath)计算出绝对目录再拼出**/*.{js,jsx,mjs}typescript: true时扩展为**/*.{ts,tsx,js,jsx,mjs}的文件扫描模式并排除node_modules与doczrc.js。也就是说typescript: true在这里是必需的——只有开启后扫描模式才会包含ts/tsx后缀packages/alert-ts中的src/index.tsx才能被 docgen 命中。filterComponents自定义组件白名单searchPath决定扫描哪些文件而filterComponents决定这些文件里哪些被真正当作“组件”处理。docz 内置了一个默认过滤器定义在 core/docz-core/src/config/docz.ts 的doczRcBaseConfig中排除*.test.*/*.spec.*测试文件只保留大写字母开头的组件文件/\/[A-Z]\w*\.(js|jsx|ts|tsx)$/、index文件/\/index\.(js|jsx|ts|tsx)$/以及含 JSX/TSX 的文件。本示例在默认策略之上做了定制其规则可拆解为/\/([A-Z]\w*)\.(js|jsx|ts|tsx)$/——保留以大写字母开头的组件文件与内置规则一致filepath.includes(/alert/index.js)——额外放行packages/alert/index.js。由于内置默认过滤器在isCalledIndex正则中使用的是非捕获分组/(js|jsx|ts|tsx)$/而packages/alert/index.js恰好符合index文件的形态这里显式 includes 是为了保证该入口文件一定被纳入同时也让index.js这种小写入口能被 docgen 识别为组件filepath.includes(/alert-ts/src/index.tsx)——额外放行TypeScript 版组件的入口文件。这一函数会在 core/docz-core/src/states/props.ts 的initial状态初始化流程中被调用fastglob(pattern)扫描文件 →filterComponents(files)过滤 →docgen(filtered, config)批量生成组件元数据最终写入props状态供Props of{...} /组件消费。文档内容一份 mdx 同时文档化 JS 与 TS 组件文档主页 index.mdx 展示了跨包引用的完整写法--- name: Getting Started route: / --- import Alert from alert import { Props } from docz ## Alert AlertHello/Alert Props of{Alert} / import AlertTS from alert-ts/src/ ## Alert TypeScript AlertTSHello/AlertTS Props of{AlertTS} /要点拆解import Alert from alert直接按包名导入packages/alert其main指向index.js无需关心它在 monorepo 中的相对位置import AlertTS from alert-ts/src/导入 TypeScript 版组件配合文档包的 tsconfig.json其中include: [../alert-ts/src/]确保 TS 源码可被解析Props of{Alert} /与Props of{AlertTS} /分别渲染两个版本的 props 表格其元数据即来自上文 docgen 的扫描结果。两个被文档化的组件本体也值得对照阅读JavaScript 版 packages/alert/index.js通过Alert.propTypes { kind: t.oneOf([info, positive, negative, warning]) }声明 props由 react-docgen 解析TypeScript 版 packages/alert-ts/src/index.tsx通过interface Props { kind: Kind }声明 props由 TypeScript 编译器 API 解析见 core/docz-core/src/utils/docgen/typescript.ts。底层原理docgen 如何为跨包组件生成元数据docz 的组件属性文档能力由docgen管线提供docgenConfig中可用的字段包括searchPath、searchPatterns、resolver、propFilter等类型定义见 core/docz-core/src/config/argv.ts 中的DocgenConfig。从 core/docz-core/src/states/props.ts 可以看到getPattern会优先使用searchPatterns自定义模式其次才使用searchPath拼接默认模式——因此如果你的 monorepo 结构更复杂例如组件分散在多个子目录可以直接提供更精确的 glob 数组。而filterComponents之后docgen 会按文件后缀分流JavaScript/JSX 文件走 core/docz-core/src/utils/docgen/javascript.ts使用docgenConfig.resolver || doczResolver作为解析器读取propTypesTypeScript/TSX 文件走 core/docz-core/src/utils/docgen/typescript.ts支持docgenConfig.propFilter与componentNameResolver等高级定制。此外docz 在文件变更时会增量更新元数据change/remove状态动作因此 dev 模式下新增、修改、删除组件都会自动反映到Props /表格中无需重启。小结与延伸阅读monorepo-separate-docs示例回答了 monorepo 场景下的一个典型问题如何让文档包与业务包解耦同时仍能自动生成组件 API 文档。核心结论可归纳为docgenConfig.searchPath控制 docgen 的扫描目录本示例设为../使扫描范围覆盖整个 monorepofilterComponents控制哪些文件被视为组件可按需放行index.js/index.tsx等非大写入口文件typescript: true让扫描模式包含ts/tsx后缀是 TS 组件被识别的先决条件Props of{Component} /直接消费 docgen 元数据实现“零手写”的 API 文档。如果想深入了解 docz 的配置项全貌可阅读 core/docz-core/src/config/docz.ts其他 monorepo 相关示例还包括 examples/monorepo业务包内自带文档与 examples/monorepo-package文档内聚于单包等可以对照理解不同组织方式下的配置差异。赞分享文档静态站点开发工具【免费下载链接】docz✍ It has never been so easy to document your things!项目地址https://gitcode.com/gh_mirrors/do/docz点击查看免费下载相关推荐3步告别复杂图表工具用代码思维重新定义技术可视化3步告别复杂图表工具用代码思维重新定义技术可视化 想象一下这样的场景你正在为一个重要的技术方案会议做准备需要在30分钟内制作一个清晰的系统架构图。你打开传文档静态站点开发工具Docz Monorepo 实践指南在 Monorepo 独立包内使用 Docz 构建组件文档Docz Monorepo 实践指南在 Monorepo 独立包内使用 Docz 构建组件文档 Docz 官方仓库中的 examples/monorepo p文档静态站点开发工具在 Monorepo 中为 TypeScript 组件包搭建独立的 Docz 文档站点alert-ts 实践详解在 Monorepo 中为 TypeScript 组件包搭建独立的 Docz 文档站点alert ts 实践详解 本文以 docz 仓库中 examples/文档静态站点开发工具上一篇如何快速掌握GuoFeng3古风AI绘画面向新手的完整指南下一篇DeepEval终极指南5步构建企业级LLM评测框架的完整方案创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考