背景
在 HiUI V4 过去的版本中，对于组件的文档需要手动编写，经常出现”动一处，手动改多处”的情况，而且最糟糕的是改动点分散在不同的文件中，整体维护效率非常低下。
比如：对于某个组件，当需要扩展一个功能 API 时，往往需要在不同位置的文件去进行更新：
- 添加 props 定义以及注释（代码源文件）
- 手动添加组件的 TS 类型定义（类型定义文件）
- 修改组件的 API 使用文档（文档内容文件）
- 补充示例代码（文本字符串示例文件）
那么对于 60+ 数量的组件，编写成本是非常巨大的，甚至经常会编写遗漏，同时综合考虑后续长期的维护成本，我们决定尝试自动化的方式来解决组件文档的管理和维护的问题。另外，也是为未来 CI 自动化发布文档站做铺垫。
可行性分析
首先，我们得先了解下官网中组件页面的可视化文档是怎么来的？包含了哪些内容？看看能否实现自动化生成？
A1：在过去的版本中，组件的使用文档都是 MarkdownX 文件，通过预渲染手段，最终生成的组件文档可视化的静态页面。
那么我们可以确定我们文档产物的格式，也就是 MarkdownX 文件。
MarkdownX：又名 MDX，支持 JSX 语法渲染的 Markdown 文件，是 Markdown 的超集。
A2：关于文档的内容，我们可以根据最终展示给用户的可视文档内容进行倒推，如下图。
可以看到，最终我们期望的 MDX 文件内容其实一共可以由以下三个部分组成。
A3：答案是肯定的。
每个组件的文档的格式以及内容都是一致且固定的，我们只需要通过一定的约定以及脚本工具串联就能完成文档的生成。
文档产物如何生成
这里我们首先约定一套 MDX 文档产物的格式规范，然后基于约定的格式去完成产物的自动生成工作。
可以看到，最终每个组件的使用文档其实对应就是三个 mdx 文件，然后通过预渲染生成我们想要的静态页面。这里我们还要关注每个组成部件从哪儿来，如何生成最终的 mdx。
组件概览
组件名\一句话介绍
考虑这部分内容完全与代码无关，我们就直接使用 mdx 文件手动编写维护。
我们约定我们手动编写的 mdx 源文件叫做 hi-doc.config.mdx，其中包含组件概览等内容。
组件示例
示例标题\描述\源代码
因为我们组件的开发基座是 Storybook，对于示例代码，我们完全可以复用 story 示例代码（在之前示例是通过代码字符串维护 eval 执行的，没有代码格式化也没有代码提示，维护效率非常低）。
但是对于示例标题和描述如何维护呢？这里我们采用就近维护原则，对于每一个 story 我们通过函数注解来申明其标题和描述，最后通过解析生成 MDX 内容。
通过上述编写格式约定，我们的技术方案工作流程大致如下：
组件 API
定义\说明\类型\可选值\默认值
关于组件 API 部分，其实我们在写组件时就已经借助 TS 定义好了，如果重复编写 Markdown 成本是非常巨大的，那么我们如何才能快速的得到完整的 API 文档呢？
这里我们也期望和示例一样，通过类型注解及TS类型就近维护我们的 API 说明的信息，就像下图这样呢？
这里，我们可以采用了社区的 react-docgen-typescript 来辅助我们做这件事情，整个文档生成工作流程如下：
最终我们完成了文档产物的生成，其本质就是生成 3 个 mdx 文件，整个方案的核心就是约定好产物的格式，然后按约定去生成。
流程串联
最后，我们把整个文档生成的工作进行流程化。因为我们每个组件都是单独的文件夹，我们可以把 hi-doc.config.mdx放在组件文件夹根目录下，然后通过扫描它判断该组件是否需要进行文档生成。
最终，整套流程如下：
总结
目前，我们已经完成了上述流程的脚本化，执行一条命令，就能实现所有组件使用文档生成的效果。后续再配合 CI 自动化，完全可以将组件文档的人力维护成本降到最低。
同时，在后续我们可以把这套模式抽离封装成工具库。那么，对于任何物料组件的生产，都可以基于这套模式和规范进行组件开发和编写，最终实现组件文档”边开发边产出“的目的，大大提高研发生产效率。
如果大家有任何新想法或发现任何错误疑问，欢迎指出~~
