乐趣区

关于前端:你还在为组件文档烦恼吗

jiezi

前言

随着工夫的推动，业务组件也逐步丰盛起来，咱们开始搭建组件库，编写组件文档的懊恼就随之而来。

这里分享下我选取组件文档工具的经验，最终以 Docusaurus 为根底，搭建了一套开箱即用的 React 组件文档工具。

此工具通过了两年工夫的积淀也是比较稳定，所以分享进去给有须要的人员应用，间接体验可看 react-doc-starter 这个我的项目。

组件库文档工具的比照

从 0 到 1 搭建一个全新的组件库文档工具不是最优的抉择，自己先在网上搜查一些已有的解决方案。
业务我的项目技术栈是基于 React，UI 库应用的是 Antd，上面是一些计划的汇总和剖析：

  • bisheng

    Antd 官网是基于 bisheng 革新的，Antd 官网看起来是很不错，然而基于 bisheng，是须要做很多定制化的解决，不能开箱即用，上手难度绝对大。

  • Gitbook

    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: Button
route: /
---
​
import {Playground, Props} from 'docz'
import {Button} from './'
​
# Button
​
<Props of={Button} />
​
## Basic usage
​
<Playground>
  <Button>Click me</Button>
  <Button kind="secondary">Click me</Button>
</Playground>

通过一番折腾之后，借鉴 Antd 官网的款式，成果如下：

应用 Docz 后遇到的一些问题

你认为这样就解决了组件文档上的问题吗？并没有，随着组件的减少，文档的变多，docz 开发启动工夫和打包工夫越来越长，甚至达到了 5 分钟以上。

5 分钟如果是首次那也能勉强承受，然而新建一个文件，服务出错，又须要重新启动服务，而后期待。。。

起初组件开发由 JavaScript 转 TypeScript，尽管 Docz 官网是反对 TypeScript，然而尝试迁徙过来的时候，发现比拟耗时间。

应用 Docz 遇到以下问题：

  • 组件文档变多之后，服务启动和打包工夫有点久，开发效率有影响
  • 文档迁徙 TypeScript 的老本绝对高，除开 Demo 和 md 文件可大部分复用，文档工具根本须要从头再来。
  • 不反对类库模式的文档快捷生成

  • Playground 组件中代码无奈应用独立文件 

    import {Playground} from 'docz'
import {Counter} from './Counter'
​
# Counter
​
<Playground>
  {() => {const [counter, setCounter] = React.useState(0)
    return (
      <Counter
        value={counter}
        onChange={() => setCounter(counter => counter+1)}
      />
    )
  }}
</Playground>

Docz 的代替计划 docusaurus

2020 年初的时候，选取了 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: Alert
menu: Components
---
​
import {Playground, Props} from 'docz'
import {Alert} from './Alert'
​
# Alert
​
## Properties
​
<Props of={Alert} />
​
## Basic usage
​
<Playground>
  <Alert>Some message</Alert>
</Playground>
​
## Using different kinds
​
<Playground>
  <Alert kind="info">Some message</Alert>
  <Alert kind="positive">Some message</Alert>
  <Alert kind="negative">Some message</Alert>
  <Alert kind="warning">Some message</Alert>
</Playground>
​

鉴于下面的应用形式，有两点思考：

  • 能不能间接应用 Playground 和 Props 组件，而无需 import ?
  • Playground 能不能通过门路援用 Demo 文件来实现展现组件成果和代码？

其实是能够的，通过 webpack loader 的形式，自己实现了 PropsTable 和 CodeShow 两个组件（其实能够了解为 jsx 的语法糖），上面介绍下这两个组件。

PropsTable 组件 
<PropsTable src="$components/Table" showDescriptionOnSummary />

PropsTable 默认只读取 export default 的组件正文，正文规定须要满足 react-docgen 的正文形式，具体的例子可看 react-doc-starter 这个我的项目。

成果如下图所示：

CodeShow 组件 
<CodeShow file="$demo/ProContent/Basic.tsx" />
<CodeShow fileList={['$demo/ProContent/Basic.tsx', '$demo/ProContent/Basic.module.less']} />

之所以不叫 Playground 是因为 CodeShow 组件不反对动静批改代码，同时 CodeShow 组件还反对多文件的代码展现（例子的渲染只渲染第一个文件的代码），具体的例子可看 react-doc-starter 这个我的项目。

成果如下图所示：

那类库的文档呢，持续手写 markdown？

实现了 PropsTable 和 CodeShow 其实曾经根本满足了 React 组件文档的疾速编写需要。

然而业务上也有一些 Utils（工具函数）的积淀，如果要同时在 React 组件文档工具中编写，则须要依照原始的 markdown 写法来实现，无奈间接读取正文，效率会绝对低。

所以自己又开始在网上找寻了生产类库文档的解决方案，最终微软的 tsdoc 进入了我的眼帘，通过 tsdoc 获取正文数据，而后联合 babel-parser 解析进去的 AST 组件 props 数据，最终实现了可在 mdx 应用的 TsDoc 组件。

<TsDoc src="$utils/createFullscreen" />

成果如下图所示：

实现 Demo 跳转 CodeSandbox

Demo 在 CodeSandbox 中运行是精益求精的，可有可无，也没有特地简单。

CodeSandbox 的原理就是通过文件的文本生成 URL 字符串参数，关上 URL 后参数中的字符串会还原成文件构造和内容。

尽管是不简单，然而还是踩了一些坑：

  • 因为 create-react-app-typescript 不反对 less module 的用法，应用 craco 来快捷反对此性能，却发现怎么都无奈反对 less module 的性能。自己猜 CodeSandbox 外部原本就做了一些模板的反对，配置 craco 有效。
  • 应用 vite 反对 less module，性能是实现了，然而关上的时候，须要运行终端装置依赖包（绝对慢点），而且在线批改代码不能立刻失效，刷新页面大部分状况下也会重新安装依赖包。总的来说就是运行速度绝对慢。

最终还是放弃了反对 less module 的性能，采纳 create-react-app-typescript 模板，而后应用原始的 css 性能实现 demo 的性能。

最终成果

间接体验可看点击这里。

后续的一些想法

react-doc-starter 目前基于 docusaurus 实现的文档工具适宜基于第三方组件的业务组件文档，如果是像 Antd 这类自研的组件，则须要而外适配一套 UI presets 来替换 @docusaurus/preset-classic，如果有工夫自己也打算实现一套 Antd 官网的主题进去。

react-doc-starter 目前 PropsTable 也只能读取默认导出的组件，其余 ts interface 的正文还不反对读取，后续可能会应用 typedoc 来实现。

退出移动版