前言随着时间的推移，业务组件逐渐丰富。我们开始构建组件库，编写组件文档的麻烦随之而来。这里分享一下我选择组件文档工具的心得，最终基于Docusaurus搭建了一套开箱即用的React组件文档工具。这个工具经过两年的沉淀，比较稳定，分享给需要的人。直接体验可以看react-doc-starter项目。具体实现细节可以看这篇文章，教你如何快速搭建一个React组件库。组件库文档工具从0到1的比较构建一个全新的组件库文档工具并不是最好的选择。我先在网上搜索一些现有的解决方案。业务项目技术栈基于React，UI库使用Antd。下面是一些解决方案的总结分析：bisheng，antd官网是基于bisheng改造的，antd官网看起来很不错，但是基于bisheng，需要做很多定制化处理不能开箱即用，而且上手难度相对较大。Gitbook，大家基本都知道，gitbook2也支持github在线阅读和生成，但是不能支持组件demo的展示。Gatsby插件生态丰富，但学习成本相对较高，更适合搭建门户网站。VuePress是Vue官方文档使用的文档工具，开箱即用，简单易用，但它不是React技术栈。Docz，基于Gatsby，开箱即用地支持mdx，是一个比较合适的组件文档工具。Docusaurus，开箱即用，由facebook团队推出。支持mdx，也适用于构建React组件文档。目前create-react-app官方文档使用的是Docusaurus。工具选择的曲折之路Docz的尝试2020年初选择了Docz，因为Docz开箱即用，支持mdx语法，提供方便的Props和Playgroud组件。Props组件可以读取组件的注解生成API，Playgroud组件可以运行mdx文件中的Demo组件，同时查看运行代码。示例如下：---name:Buttonroute:/---import{Playground,Props}from'docz'import{Button}from'./'#Button##基本用法点我折腾了好久，借鉴了antd官网的风格，效果如下：使用Docz后遇到的一些问题你认为这会解决组件文档上的问题吗？这不，随着组件的增多，文档的增多，docz开发的启动时间和打包时间越来越长，甚至达到5分钟以上。5分钟如果是第一次勉强可以接受，但是如果新建文件，服务失败，需要重启服务，然后等待。..后来，组件开发从JavaScript变成了TypeScript。虽然Docz官方支持TypeScript，但在尝试迁移它时，发现它很耗时。使用Docz遇到以下问题：组件文件数量增加后，服务启动和打包时间有点长，影响开发效率。文档迁移到TypeScript的成本相对较高。除了Demo和md文件，大部分都可以复用，文档工具基本上需要从头开始。.不支持类库模式的文档快速生成。Playground组件中的代码不能使用单独的文件import{Playground}from'docz'import{Counter}from'./Counter'#Counter{()=>{const[counter,setCounter]=React.useState(0)return(setCounter(counter=>counter+1)}/>)}}Docz的替代docusaurus2020年初，Docz被选中，但没有注意到Docusaurus。后来，Docz开始做服务开发文档的时间越来越长，同时决定从JavaScript转向TypeScript。2020年年中，我开始寻找Docz的替代品。经过多次搜索，没有找到Docz的合适替代品。终于，Docusaurus进入了我的视线。深入了解后，Docusaurus使用起来比较简单（个人理解就是React界的VuePress），支持mdx，扩展性强。但是Docusaurus不支持类Docz的Props和Playground组件，不支持便捷的生成API，不能同时展示Demo组件效果和代码，需要做一些处理才能达到类似Docz使用的效果。思考Docz的Playground和Props组件首先看Docz的Playground和Props组件是如何使用的：---name:Alertmenu:Components---import{Playground,Props}from'docz'import{Alert}from'./Alert'#Alert##Properties##基本用法一些消息##不同种类的使用一些消息一些消息一些消息一些留言针对上面的用法，有两个考虑：Playground和Props组件是否可以不导入直接使用？Playground能否通过路径引用Demo文件实现显示组件效果和代码？事实上，这是可能的。通过webpackloader的方式，我实现了两个组件PropsTable和CodeShow（其实可以理解为jsx的语法糖），下面分别介绍这两个组件。PropsTable组件PropsTable默认只读取导出默认组件评论，评论规则需要满足react-docgen的评论方式。有关详细示例，请参阅react-doc-starter项目。效果如下图：basic.module.less']}/>不叫Playground是因为CodeShow组件不支持动态代码修改，CodeShow组件也支持多文件代码显示（示例的渲染只渲染第一个文件的代码),详细示例可以在查看react-doc-starter项目中找到。效果如下图：那类库的文档呢，继续手写markdown？PropsTable和CodeShow的实现已经基本满足了React组件文档的快速编写需求。但是，业务中也有一些Utils（实用函数）。如果要同时在React组件文档工具中编写，需要在原有的markdown编写方式中实现。不能直接看评论，效率会比较低。于是开始在网上寻找制作类库文档的方案。终于，微软的tsdoc进入了我的视线。通过tsdoc获取注解数据，再结合babel-parser解析出来的AST组件props数据，终于意识到可以在mdx使用的TsDoc组件中使用。效果如下图所示：实现Demo跳转CodeSandboxDemo在CodeSandbox中运行是锦上添花，可有可无，并不是特别复杂。CodeSandbox的原理是通过文件的文本生成URL字符串参数。打开URL后，参数中的字符串将恢复为文件结构和内容。虽然不复杂，但还是有一些坑：由于create-react-app-typescript不支持less模块??的使用，我用craco快速支持了这个功能，却发现不能支持less模块??的功能。估计CodeSandbox内部已经做了一些模板支持，craco的配置无效。使用vite支持less模块??，功能实现了，但是打开的时候需要运行终端安装依赖包（比较慢），而且在线修改代码不能立即生效，刷新一下大多数情况下页面也会重新安装依赖包。一般来说，运行速度比较慢。最终我放弃了支持less模块??的功能，采用了create-react-app-typescript模板，然后利用原有的css功能实现了demo功能。最终效果可以点击这里直接体验。一些后续的想法react-doc-starter目前是基于docusaurus的。文档工具适用于基于第三方组件的业务组件文档。如果是像Antd这样的自研组件，需要适配一套UI预设来替换@docusaurus/preset-classic，如果有时间我也打算实现一套Antd官网主题。react-doc-starter目前PropsTable默认只能读取导出的组件。其他ts接口注释不支持读取，以后可能会使用typedoc来实现。
