React 通過注釋自動生成文檔

最近找了一些文檔的生成工具,結果發現了這個 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 上,那么就能夠立即生成你的文檔站點