使用 React Styleguidist 编写，管理，迭代文档(已废弃)

编写文档有条不紊

文档管理是个比较繁琐的事情，如果文档和代码是分离的，代码更新了还要到对应的文档的地方做更改，很难让人持之以恒。

有没有一个方式是只需要在代码的地方写好注释，然后自动生成可交互的文档呢？

用 React Styleguidist 可以做到，但是配置比较繁琐，而且也没有中文支持，对中文用户来说很难。

开始吧

安装依赖

这里使用了 webpack-blocks, 毕竟不是每个项目都会有 webpack 配置

# 最好装一个 npx
npm i npx -g

# 然后安装
yarn add webpack react-styleguidist webpack-blocks --dev

在项目根目录创建 styleguide.config.js

const { createConfig, babel, postcss } = require('webpack-blocks')
module.exports = {
  webpackConfig: createConfig([babel(), postcss()]),
  components: 'src/core/**/**.js' // 写入对应目录的文档
}

启动文档开发模式

npx styleguidist server

# 这里是 build
npx styleguidist build

就好了，React Styleguidist 很强，会自动找所有的 src//.js 的注释，对应的文件，然后生成一份文档。

自定义样式

官方推荐在 styleguide.config.js 中写 style，并且用 React devtool 查找对应的节点，覆盖原有样式。

我觉得这样的设计糟糕透了

写到配置文件中不能实时查看样式，需要重启服务才可以看到修改结果，简直智障
很费劲去寻找那个样式 react 的组件

那其实可以换一个想法，新增一个 scss 文件，使用 css 选择器 + !important 方式去覆盖，在 styleguide.config.js 中配置 require 参数。

module.exports = {
  ...yourConfig,
  // styleguide/style.scss 自行创建
  require: path.join(__dirname, 'styleguide/style.scss'),
}

# 例如修改 sidebar 的背景颜色

[class^=rsg--sidebar] {
  background-color: #fefefe !important;
}

自定义入口 index.html 入口模版

这又是另一个智障的设计，不支持通过文件模版的方式引用，只能使用 styleguide.config.js 中的 template 字段来自定义模版，而且写法太难受了，我只想加入 loading 画面以及饮用 icon 或者其它三方库，需要如下写法

module.exports = {
  ...yourConfig,
  template: ({}) => `<!DOCTYPE html>
      <html>
        <head>
          <meta charset="UTF-8">
          <title>${title}</title>
          ${generateCSSReferences(css, publicPath)}
          <link rel="stylesheet" href="./resource/loading.css">
        </head>
        <body>
          <div id="rsg-root"></div>
            <div class="sk-folding-cube" id="loadingBg">
            <div class="sk-cube1 sk-cube"></div>
            <div class="sk-cube2 sk-cube"></div>
            <div class="sk-cube4 sk-cube"></div>
            <div class="sk-cube3 sk-cube"></div>
          </div>
          ${generateJSReferences(js, publicPath)}
        </body>
      </html>
      <link rel="stylesheet" href="https://use.fontawesome.com/releases/v5.3.1/css/all.css" integrity="sha384-mzrmE5qonljUremFsqc01SB46JvROS7bZs3IO2EmfFsd15uHvIt+Y8vEf7N7fWAU" crossOrigin="anonymous">
    `
}

总结

同类型的 style guide 也有不少，不过 react styleguidist 相对完善一些

deer-ui 便是基于此方式来编写文档，虽然有些傻，但是还能接受，用 markdown 的方式来写例子，更好维护和查看了

编写文档有条不紊

开始吧

自定义样式

自定义入口 index.html 入口模版

总结

参考