react-styleguidist是一个基于JSDOC可以帮助react项目快速构建项目文档的一个插件。
一、简单入门
1.1 环境准备
准备一个新鲜的react项目(非必需)
npx create-react-app react-app
添加react-styleguidist
npm install --save-dev react-styleguidist
在package.json添加启动脚本
"scripts": { ... "styleguide": "styleguidist server", "styleguide:build": "styleguidist build" }
1.2 写一个button组件
在src/components/Button下新建两个文件：index.js、index.css
// index.js import React from 'react'; import PropTypes from 'prop-types'; import './Button.css'; /** * The only true button. */ export default function Button({ color, size, onClick, disabled, children }) { const styles = { color, fontSize: Button.sizes[size], }; return ( <button className="button" style={styles} onClick={onClick} disabled={disabled}> {children} </button> ); } Button.propTypes = { /** Button label */ children: PropTypes.node.isRequired, /** The color for the button */ color: PropTypes.string, /** The size of the button */ size: PropTypes.oneOf(['small', 'normal', 'large']), /** Disable button */ disabled: PropTypes.bool, /** Gets called when the user clicks on the button */ onClick: PropTypes.func, }; Button.defaultProps = { color: '#333', size: 'normal', onClick: event => { // eslint-disable-next-line no-console console.log('You have clicked me!', event.target); }, }; Button.sizes = { small: '10px', normal: '14px', large: '18px', }; // index.css .button { padding: 0.5em 1.5em; color: #666; background-color: #fff; border: 1px solid currentColor; border-radius: 0.3em; text-align: center; vertical-align: middle; cursor: pointer; } .button[disabled] { opacity: 0.35; cursor: default; } .button + .button { margin-left: 8px; } .checks { background-image: linear-gradient(45deg, #f5f5f5 25%, transparent 25%), linear-gradient(-45deg, #f5f5f5 25%, transparent 25%), linear-gradient(45deg, transparent 75%, #f5f5f5 75%), linear-gradient(-45deg, transparent 75%, #f5f5f5 75%); background-size: 16px 16px; background-position: 0 0, 0 8px, 8px -8px, -8px 0px; }
1.3 生成文档
运行yarn styleguide就可以启动文档服务器了。打开localhost:6060：
1.4 总结
styleguide会默认为src/components/**/*.js的js文件生成文档。通过生成的styleguide文档我们可以看出，styleguide读取了注解、Button.propTypes和Button.defaultProps为我们生成了组件文档，并且将propTypes的注解放到description中，可谓是非常贴心了。
注意：styleguide读取的是注解，不是注释语句
二、Documenting components
经过第一节，styleguide已经帮助我们生成了组件的使用文档。只有一些props的文档显然是不够的，除了JSDoc styleguide还支持markdown来生成我们自定义的文档。在src/components/Button文件夹下新建Readme.md：
// Readme.md React component example: ```js <Button size="large">Push Me</Button> ``` 通过props配置Code wrapper样式: ```js { "props": { "className": "checks" } } <Button>I’m transparent!</Button> ``` disable `view code` 按钮: ```jsx noeditor <Button>Push Me</Button> ``` `static` modifier支持js代码高亮: ```jsx static import React from 'react'; ``` 其他语言高亮: ```html <Button size="large">Push Me</Button> ```
_支持所有的_ [Markdown](http://daringfireball.net/projects/markdown/) _语法_. 刷新localhost:6060就可以看到我们组建的样例和自定义文档了。而且，我们还可以点击VIEW CODE来实时更新example代码，这样就可以面向文档编程了。更多的styleguide的知识可在官方文档按需学习，高阶用法请参考Cookbook。
。
三、配置
我们之前启动都styleguide server都是使用了styleguide的默认配置，styleguide默认会读取项目根目录下的styleguide.config.js来替换默认配置，当然也可以使用--config来指定配置文件。官方文档--配置。
四、TS
styleguide也支持了Typescript，只需要添加react-docgen插件就可以了。
安装插件
npm i -D react-docgen-typescript
配置插件，在styleguide.config.js中添加：
module.exports = { ... resolver: require('react-docgen').resolver.findAllComponentDefinitions, propsParser: require('react-docgen-typescript').parse, webpackConfig: require('./config/webpack.config') }
区别于普通的react，ts的props是通过interface来声明的。所以在ts中就不需要写propTypes了。
作者：zhiqiangx
链接：https://www.jianshu.com/p/5d6de52f7b57
来源：简书
著作权归作者所有。商业转载请联系作者获得授权，非商业转载请注明出处。
