关于组件文档从编写到生成的那些事

前言

说到前端领域的组件，Vue 技术体系下有 Element UI，React 技术体系下有 Ant Design，这些都是当前的前端攻城狮们都免不了要实际使用到的基础组件库。而在实际工作中，我们也总免不了要根据自己的工作内容，整理一些适合自己业务风格的一套组件库，基础组件部分可以基于上面开源的组件库以及 less 框架等多主题样式方案做自己的定制，但更多的是一些基于这些基础组件整理出适合自己业务产品的一套业务组件库。

而说到开发组件库，我们或选择 Monorepo 单仓库多包的形式（参考网文 https://segmentfault.com/a/11... 等）或其他 Git 多仓库单包的形式来维护组件代码，最终都免不了要将组件真正落到一个文档中，提供给其他同事去参考使用。

本篇文章就产出组件文档这件事，聊聊我在产出文档过程中的一系列思考过程，解决组件开发这「最后一公里」中的体验问题。

组件文档的编写

规范与搭建的调研

组件文档是要有一定的规范的，规范是任何软件工程阶段的第一步。对于组件来说，文档透出的内容都应包含哪些内容，决定着组件开发者和使用者双方的所有的体验。确定这些规范并不难，参考开源的组件库的文档，我们会有一些初步的印象。

因为我们团队使用的是 React 技术栈，这里我们参考 Ant Design 组件库。

比如这个最基本的 Button 组件，官方文档从上至下的内容结构是这样：

显示组件标题，下跟组件的简单描述。
列出组件的使用场景。
不同使用场景下的效果演示、代码案例。可外跳 CodeSandbox、CodePen 等在线源码编辑器网站编辑实时查看效果。
列出组件可配置的属性、接口方法列表。列表中包含属性/方法名、字段类型、默认值、使用描述等。
常见问题的 FAQ。
面向设计师的一些 Case 说明链接。

这些文档内容很丰富，作为一个开放的组件库，几乎考虑到的从设计到开发视角的方方面面，使用体验特别好。而在好奇心驱使下，我去查看了官网源码方库，比如 Button 组件：https://github.com/ant-design...。在源码库下，放置了和组件入口文件同名的分别以 .zh-CN.md 和 .en-US.md 后缀命名的 Markdown 文件，而在这些 Markdown 文件中，便是我们看到的官网文档内容...咦？不对，好像缺少了什么，案例演示和示例代码呢？

难道 AntD 官网文档是另外自己手动开发维护的？这么大的一个项目肯定不至于，根据其官网类似 docs/react/introduce-cn 这种访问路径在源码库中有对应的 Markdown 文件来看，官网的文档肯定是官方仓库根据一种规范来生成的。那么是怎么生成的呢？第一次做组件文档规范的我被挑起了兴趣。

而作为一个前端工程老手，我很熟练地打开了其 package.json 文件，通过查看其中的 scripts 命令，轻易便发现了其下的 site 命令（源码仓库 package.json）:

npm run site:theme && cross-env NODE_ICU_DATA=node_modules/full-icu ESBUILD=1 bisheng build --ssr -c ./site/bisheng.config.js

原来如此，网站的构建使用了 bisheng。通过查阅了解 bisheng 这个工具库，发现它确实是一个文档系统的自动生成工具，其下有一个插件 bisheng-plugin-react，可以将 Markdown 文档中的 JSX 源码块转换成可以运行演示的示例。而每个组件自身的示例代码文档，则在每个组件路径下的
demo 目录下维护。

Emmm，bisheng 确实是很好很强大，还能支持多语言，结合一定的文档规范约束下，能够快速搭建一个文档的主站。但在深入了解 bisheng 的过程中，发现其文档相对来说比较缺乏，包装的东西又那么多，使用过程中黑盒感严重，而我们团队的组件库其实要求很简单，一是能做到方便流通，而是只在内部流通使用，不会开源。那么，有没有更简单的搭建文档的方式呢？

组件文档的生成

在多方对比了多个文档搭建的工具库后，我最终还是选用了 React Styleguidist。在我看来，自然是其基于 react-docgen 来实现解析组件属性、类型、注释描述等的功能吸引到了我，这个功能一方面能在较少的额外时间付出下规范团队同事开发组件过程中一系列规范，另一方面其 API 接口的接入形式能够通过统一构建配置而统一产出文档内容格式和样式，方便各业务接入使用。

决定了技术方案后，便是如何具体实现基于其封装一个工具，便于各业务仓库接入了。

我们团队有自己统一的 CLI 构建工具，再多一个 React Styleguidist 的 CLI 配置会在理解上有一定的熟悉成本，但我可以基于 React Styleguidist 的 Node API 接入形式，将 React Styleguidist 的功能分别融入我们自身 CLI 的 dev 和 build 命令。

首先，基于 React Styleguidist API 的形式，统一一套配置，将生成 React Styleguidist 示例的代码抽象出来：

// 定义一套统一的配置，生成 react-styleguidist 实例
import styleguidist from 'react-styleguidist/lib/scripts/index.esm';
import * as docgen from 'react-docgen';
import * as docgenTS from 'react-docgen-typescript';

import type * as RDocgen from 'react-docgen';

export type DocStyleguideOptions = {
  cwd?: string;
  rootDir: string;
  workDir: string;
  customConfig?: object;
};

const DOC_STYLEGUIDE_DEFAULTS = {
  cwd: process.cwd(),
  rootDir: process.cwd(),
  workDir: process.cwd(),
  customConfig: {},
};

export const createDocStyleguide = (
  env: 'development' | 'production',
  options: DocStyleguideOptions = DOC_STYLEGUIDE_DEFAULTS,
) => {
  // 0. 处理配置项
  const opts = { ...DOC_STYLEGUIDE_DEFAULTS, ...options };
  const {
    cwd: cwdPath = DOC_STYLEGUIDE_DEFAULTS.cwd,
    rootDir,
    workDir,
    customConfig,
  } = opts;

  // 标记：是否正在调试所有包
  let isDevAllPackages = true;

  // 解析工程根目录包信息
  const pkgRootJson = Utils.parsePackageSync(rootDir);

  // 1. 解析指定要调试的包下的组件
  let componentsPattern: (() => string[]) | string | string[] = [];
  if (path.relative(rootDir, workDir).length <= 0) {
    // 选择调试所有包时，则读取根路径下 packages 字段定义的所有包下的组件
    const { packages = [] } = pkgRootJson;
    componentsPattern = packages.map(packagePattern => (
      path.relative(cwdPath, path.join(rootDir, packagePattern, 'src/**/[A-Z]*.{js,jsx,ts,tsx}'))
    ));
  } else {
    // 选择调试某个包时，则定位至选择的具体包下的组件
    componentsPattern = path.join(workDir, 'src/**/[A-Z]*.{js,jsx,ts,tsx}');
    isDevAllPackages = false;
  }

  // 2. 获取默认的 webpack 配置
  const webpackConfig = getWebpackConfig(env);

  // 3. 生成 styleguidist 配置实例
  const styleguide = styleguidist({
    title: `${pkgRootJson.name}`,
    // 要解析的所有组件
    components: componentsPattern,
    // 属性解析设置
    propsParser: (filePath, code, resolver, handlers) => {
      if (/\.tsx?/.test(filePath)) {
        // ts 文件，使用 typescript docgen 解析器
        const pkgRootDir = findPackageRootDir(path.dirname(filePath));
        const tsConfigParser = docgenTS.withCustomConfig(
          path.resolve(pkgRootDir, 'tsconfig.json'),
          {},
        );
        const parseResults = tsConfigParser.parse(filePath);
        const parseResult = parseResults[0];
        return (parseResult as any) as RDocgen.DocumentationObject;
      }
      // 其他使用默认的 react-docgen 解析器
      const parseResults = docgen.parse(code, resolver, handlers);
      if (Array.isArray(parseResults)) {
        return parseResults[0];
      }
      return parseResults;
    },
    // webpack 配置
    webpackConfig: { ...webpackConfig },
    // 初始是否展开代码样例
    // expand: 展开 | collapse: 折叠 | hide: 不显示;
    exampleMode: 'expand',
    // 组件 path 展示内容
    getComponentPathLine: (componentPath) => {
      const pkgRootDir = findPackageRootDir(path.dirname(componentPath));
      try {
        const pkgJson = Utils.parsePackageSync(pkgRootDir);
        const name = path.basename(componentPath, path.extname(componentPath));
        return `import ${name} from '${pkgJson.name}';`;
      } catch (error) {
        return componentPath;
      }
    },
    // 非调试所有包时，不显示 sidebar
    showSidebar: isDevAllPackages,
    // 日志配置
    logger: {
      // One of: info, debug, warn
      info: message => Utils.log('info', message),
      warn: message => Utils.log('warning', message),
      debug: message => console.debug(message),
    },
    // 覆盖自定义配置
    ...customConfig,
  });

  return styleguide;
};

这样，在 dev、build 命令下可以分别调用实例的 server 接口方法和 build 接口方法来实现调试和构建产出文档静态资源。

// dev 命令下启动调试
// 0. 初始化配置
const HOST = process.env.HOST || customConfig.serverHost || '0.0.0.0';
const PORT = process.env.PORT || customConfig.serverPort || '6060';

// 1. 生成 styleguide 实例
const styleguide = createDocStyleguide(
  'development',
  {
    cwd: cwdPath,
    rootDir: pkgRootPath,
    workDir: workPath,
    customConfig: {
      ...customConfig,
      // dev server host
      serverHost: HOST,
      // dev server port
      serverPort: PORT,
    },
  },
);

// 2. 调用 server 接口方法启动调试
const { compiler } = styleguide.server((err, config) => {
  if (err) {
    console.error(err);
  } else {
    const url = `http://${config.serverHost}:${config.serverPort}`;
    Utils.log('info', `Listening at ${url}`);
  }
});
compiler.hooks.done.tap('done', (stats: any) => {
  const timeStr = stats.toString({
    all: false,
    timings: true,
  });

  const statStr = stats.toString({
    all: false,
    warnings: true,
    errors: true,
  });

  console.log(timeStr);

  if (stats.hasErrors()) {
    console.log(statStr);
    return;
  }
});

// build 命令下执行构建

// 生成 styleguide 实例
const styleguide = MonorepoDev.createDocStyleguide('production', {
  cwd,
  rootDir,
  workDir,
  customConfig: {
    styleguideDir: path.join(pkgDocsDir, 'dist'),
  },
});
// 构建文档内容
await new Promise<void>((resolve, reject) => {
  styleguide.build(
    (err, config, stats) => {
      if (err) {
        reject(err);
      } else {
        if (stats != null) {
          const statStr = stats.toString({
            all: false,
            warnings: true,
            errors: true,
          });
          console.log(statStr);
          if (stats.hasErrors()) {
            reject(new Error('Docs build failed!'));
            return;
          }
          console.log('\n');
          Utils.log('success', `Docs published to ${path.relative(workDir, config.styleguideDir)}`);
        }
        resolve();
      }
    },
);

最后，在组件多包仓库的每个包下的 package.json 中，分别配置 dev 和 build 命令即可。实现了支持无感启动调试和构建产出文档资源。

小结

本文主要介绍了我在调研实现组件文档规范和搭建过程中的一个思考过程，诚如文中介绍其他文档系统搭建工具时所说，有很多优秀的开源工具能够支持实现我们想要的效果，这是前端攻城狮们的幸运，也是不幸：我们可以站在前人的肩膀上，但要在这么多优秀库中选择一个适合自己的，更需要多做一些了解和收益点的权衡。一句老话经久不衰：适合自己的才是最好的。

希望这篇文章对看到这里的你能有所帮助。

作者：ES2049 / 靳志凯

文章可随意转载，但请保留此原文链接。
非常欢迎有激情的你加入 ES2049 Studio，简历请发送至 caijun.hcj@alibaba-inc.com 。

关于组件文档从编写到生成的那些事

前言

组件文档的编写

规范与搭建的调研

更多的文档工具库的调研

Docz

StoryBook

React Styleguidist

dumi

组件文档的生成

小结

ES2049

引用和评论

Web推理 - ONNX Runtime 入门

CSS团队协作规范

100个React最佳实践小技巧

不使用 JS 纯 CSS 获取屏幕宽高

前端开发工具

开发插件集合

CSS 现在终于支持高度 auto 过渡动画了