【第1497期】React组件文档解决方案
前言
今天你有到杭州D2现场么？重点是介绍这么一种工具：doc-scripts。今日早读文章由天猫@baixuan分享。
正文从这开始～～
需求
如何才能更舒适的写一个React组件？
这个问题不管是对个人，还对团队，都是一个疑难问题，它涉及的不仅仅只是工程构建的问题，还涉及了对组件的运营维护成本问题上。
总所周知，一个React组件就是一个npm包，我们往往会有如下的组件目录结构：
--- umd umd打包目录，建议用rollup打包，
--- lib babel编译后的文件
--- src 源文件
--- test 单元测试
--- .gitignore git忽略项
--- .babelrc babel配置
--- package.json npm包描述
--- README.md 组件概要描述按照上面的目录结构，我们可能只需要babel和rollup还有一个测试框架，就能搞定了。
但是，一个React UI型组件的开发，肯定还需要调样式，要调样式就得启动一个本地服务，这就涉及到构建服务了，一般都会使用webpack dev server，但是webpack这玩意，再牛逼的前端每次使用的时候都可能需要看一下文档，因为它的配置项真的实在太多，所以这个拦路虎真的太狠了，我们的原始需求无非就是 调样式，本来可以几分钟搞定的事情，看webpack文档到配置，整个过程至少也得花一个小时以上，一天也就8个小时，浪费这么多时间就等于浪费了自己往上晋升的机会，所以，对于 调样式 的需求，我们希望做到0配置。
方案
幸好，现在我们有了create-react-app这个工具，它可以快速启动一个服务来跑React组件，其实它里面是用了一个叫做react-scripts的cli工具来解决构建打包和调样式的需求，但是，对于一个React组件来说，它并不是属于一个react app，结果，我们为了 调样式 ，还不得不建一个应用型仓库，这其实也是一个浪费时间的过程，所以，后来，我们有了create-react-library 这个工具，它直接帮你初始化好了组件仓库，并建好了一个example的应用仓库，让你可以快速在example里 调样式 。
文档该如何写？
到现在为止，create-react-library的确解决了我们的原始需求：
0 配置创建组件模板仓库
0 配置调样式
但是，到最后，我们的组件是要给别人用的，所以，就得写文档了，一个README.md文件肯定不能作为组件文档，它更多的是作为一个组件概要而存在，所以，到现在，我们还需要一个真正的组件型文档。它要包含：
用例的描述型介绍
用例的可执行代码
API文档
文档可生成静态网站
方案
介绍
doc-scripts 就是为了解决以上所有需求而存在的，它是一个React组件文档构建工具，它主要有以下几个特性：
0配置，调样式+写文档一键开始
Markdown驱动，自动扫描仓库内的所有md文件做解析合并，并优雅展示。
代码高亮，JSX代码可运行
支持Emoji
可以生成静态网站，其实就是一个bundle js
生成的网站样式很好看
自定义配置能力
可以在Codesandbox和iframe里嵌入使用
安装
我们可以使用yarn或者npm全局或者仓库本地安装doc-scripts
yarn global add doc-scripts
or
yarn add doc-scripts [--dev]
or
npm install -g doc-scripts
or
npm install --save-dev doc-scripts使用
本地服务
很简单，我们只需要执行以下命令则可快速启动服务做调样式与写文档的工作：
doc-scripts start静态构建
如果我们想给组件一个文档网站，让用户快速访问，必然要面临将文档打包成网站的需求，所以执行以下命令即可快速构建一个静态网站，它会在您仓库上建一个doc-site的目录来放静态文件：
doc-scripts build自定义扩展配置
有些时候，我们的文档希望自己定制一些样式，或者希望文档构建服务加入一些webpack插件，我们可以使用以下方案来做自定义扩展配置
Webpack 扩展配置
创建一个名为 doc-scripts.config.js 的文件放到仓库根目录中，配置格式是webpack的配置格式，支持自动merge形式与覆盖形式配置
module.exports = {
module:{
rules:[]
},
plugins:[]
}
//or
module.exports = function(config){
return {
...config,
module:{
rules:[]
},
plugins:[]
}
}Demo HTML 模板配置
创建名为 doc-scripts.header.html 的文件或者 doc-scripts.footer.html的文件放到仓库根目录，文件格式就是正常的html格式，它们会分别插入到Demo HTML的的header和footer中，帮助您快速依赖一些第三方样式或者js库
<!-- this is doc-scripts.header.html -->
<link rel="stylesheet" href="//unpkg.com/@alifd/next/dist/next.min.css"/>总结
是不是发现，有了doc-scripts之后，我们调样式的需求，其实就是在写文档的过程中给搞定了，这是多么美好而自然的事情，如果用 create-react-library的话，我们可能还需要一个独立的文档构建工具来专门搞文档，到最后，反而觉得example目录，就有点多余了。
关于本文
作者：@baixuan
原文：https://zhuanlan.zhihu.com/p/53567112
最后，为你推荐