最近找了一些文档的生成工具,结果发现了这个 React Styleguidist
可以通过注释,自动生成对应的文档,对于 react 库来说十分方便
安装
npm i -D react-styleguidist
// or
yarn add -D react-styleguidist
typescript 支持
npm i -D react-docgen-typescript
配置
这次的例子是使用 cra 来创建的项目,还有其他项目也是支持的 点击参考
在根文件夹下创建 styleguide.config.js
文件
可以使用如下的配置
const path = require('path')
const packagePath = path.resolve(
__dirname,
'package.json'
)
const packageFile = require(packagePath)
module.exports = {
webpackConfig: require('./config/webpack.config'), // webpack 路径,可以用项目里的,也可以用webpack-blocks创建
components: 'src/component/**.tsx', // 写入对应目录的文档
propsParser: require('react-docgen-typescript').withCustomConfig(
'./tsconfig.json'
).parse, // 用来支持 tsx
verbose: true, // 打印详细信息
updateDocs(docs, file) {
if (docs.doclets.version) {
const version = packageFile.version
docs.doclets.version = version
docs.tags.version[0].description = version
}
return docs
}, // 在使用 @version 时 使用 package.json 的 version
version: packageFile.version, // 同上 使用 package.json 的 version
usageMode: 'expand', // 自动打开文档的缩放
pagePerSection: true, // 是否每页一个组件显示
title: "文档名" // 文档名
}
更加具体的配置项可以点此参考
编写注释
例子 1:
import React from 'react';
interface IProps {
/**
* 用户名
*/
name: string
/**
* 年龄
*/
age?: number
/**
* 工作
* @default doctor
*/
work?: string
/**
* 修改名字
* @param name
*/
changeName?: (name: string) => void
}
/**
* Person 组件
* @version package.json
* @visibleName Person 组件名称的显示
*/
function Person(props: IProps) {
return <div>Person</div>
}
export default Person;
添加使用用例:
import Person from './Person';
<Person name="grewer"/>
图例:
例子 2:
import React from 'react';
interface IProps {
type: 'submit' | 'button'
/**
* 尺寸
* @deprecated 使用 size2 替代
*/
size?: 'small' | 'default'
/**
* 新的尺寸
* @since 1.1.0
* @default large
*/
size2?: 'small' | 'large'
}
/**
* @link [antd button](https://ant.design/components/button-cn/) 可查看
*/
class Button extends React.Component<IProps, any> {
static config = {
desc: "这是 static 属性"
}
/**
* 点击事件
* @public
*/
clickHandle = (ev: Event) => {
console.log('!')
}
render(): React.ReactElement<any, string | React.JSXElementConstructor<any>> | string | number | {} | React.ReactNodeArray | React.ReactPortal | boolean | null | undefined {
return <div>{this.props.children}</div>
}
}
export default Button;
图例:
结果
使用如下命令,可以创建一个 web 服务,在线修改文档:
styleguidist server
使用如下命令,可以将文档项目打包
styleguidist build
如果库正好在 GitHub 上面,可是开通 GitHub Pages
功能,将文档包提交进 GitHub;
本例结果页面查看:
https://grewer.github.io/styleguidist-boilerplate/styleguide/
结语
当你使用 react 开发而又想要写文档的使用, React Styleguidist
绝对是最好的选择之一
而如果你的库在 GitHub 上,那么就能够立即生成你的文档站点
**粗体** _斜体_ [链接](http://example.com) `代码` - 列表 > 引用
。你还可以使用@
来通知其他用户。