# 编写组件文档

## 背景

主流UI组件库：

+ Bootstrap（Js+Jq）
+ Material-UI （React）
+ Ant Design （React）
+ Element （Vue）
+  iView（Vue）

通过UI 组件，前端项目就像搭积木一样简单。为了提升开发效率，沉淀一套适合自己团队的 UI 组件库是一种较为有效的方式之一：可以减少重复工作、提高可复用。

**构建思路：**在大厂开源 UI 组件库的基础上个性化色彩（一般都提供颜色定制）、增加团队的个性化需求组件、减少不需要的组件。

UI 组件库少不了使用文档，这里通过Docz+ MDX 来写 React UI 组件文档。下图左边是创建的 MDX 文档，右边是 Docz 渲染出的组件及组件代码。

![Docz 用 MDX 写 React UI 组件文档](https://img1.3s78.com/codercto/60393acda07dcbebfe5bfa952daa49fb)

> [Docz](https://github.com/pedronauck/docz) ：用于构建演示文档，其特色是零配置、简单、快速，它使用 Markdown 语法的扩展 MDX (在 Markdown 里引入 React 组件并渲染出组件)来书写文档。



非常简单！



## 使用

1. 在项目中安装 Docz：

  ```
  yarn add docz --dev 
  或
  npm install docz --save-dev
  ```

2. 创建 .mdx 文件并输入：

   ```md
   ---
   name: Button
   ---
   
   import { Playground, PropsTable } from 'docz'
   import Button from './'
   
   # Button
   
   <PropsTable of={Button} />
   
   ## Basic usage
   
   <Playground>
     <Button>Click me</Button>
     <Button kind="secondary">Click me</Button>
   </Playground>
   ```

3. 运行：

  

  ```
  yarn docz dev
  ```

  打完收工，这样你就收获了一个简单的 Button 组件的演示文档。

  ##### ![Docz 用 MDX 写 React UI 组件文档](https://img1.3s78.com/codercto/dc1fc692925ae138fc7b067dc157d3ce)

4. 构建

  ```
  yarn docz build
  ```

  更多详情，请参照[官方文档](https://www.docz.site/)。



### 编辑组件的[propTypes](https://www.npmjs.com/package/prop-types)

​	可能你发现上图中除了自己写的演示案例外，还多了一个Properies。 这个属性列表里的说明是哪来的？其实这是Docz等演示文档生成工具会直接从组件的PropTypes列表中的注释提取来的。所以你编写组件时，应该为组件编写详尽的`propTypes`注释，就像这样：

```jsx
class Button extends Component {
  static propTypes = {
  	/**
     * button的size，包括"xs","sm","md","lg","xl"，支持*markdown*
     */
    size: Proptypes.oneOf(["xs","sm","md","lg","xl"]);
    /**
     * call after button is clicked，支持*markdown*
     */
    onClick: PropTypes.func,
    
  }
  ...
}
```





## 配置

​	零配置方便是方便，但有时想界面个性化点还是很费事的(官方提供 Themes 支持，但现仅有一套官方的默认主题)，下面分享一个通过引入本地 CSS 的方式来改变默认主题的配置。

1. 创建配置文件 doczrc.js ，增加 htmlContext 内容。

> 更多配置：https://www.docz.site/documentation/project-configuration

```js
export default {
  htmlContext: {
    head: {
      links: [
        { rel: 'stylesheet', href: '/base.css' }
      ]
    }
  }
}
```

2. .docz 目录下创建 public 文件夹并创建 base.css ，在 base.css 里写自己的样式覆盖默认的即可。



## 最后

+ [Docz](https://github.com/pedronauck/docz)：简单好用，但现在只支持 React。
+ [Storybook](https://github.com/storybooks/storybook)：是一个更强大的集组件开发、查看、测试的文档工具，支持：
  - React
  - React Native
  - Vue
  - Angular
  - Polymer
  - Mithril
  - Marko
  - HTML
  - Svelte
  - Riot
+ [Docsify](https://github.com/docsifyjs/docsify)： 搭配 Vuep 写 Playground 。
+ [redemo](https://github.com/imweb/redemo)： 依赖[react-docgen](https://github.com/reactjs/react-docgen)来提取组件的`propTypes`注释。