close
Rspress
  • 中文

      • @rspress/plugin-api-docgen
      源码

      用于自动生成 API 文档描述，支持 react-docgen-typescript 和 documentation。

      安装

      npm
      yarn
      pnpm
      bun
      deno
      npm add @rspress/plugin-api-docgen -D

      使用

      首先在配置文件中写入以下的配置：

      // rspress.config.ts
import path from 'path';
import { defineConfig } from '@rspress/core';
import { pluginApiDocgen } from '@rspress/plugin-api-docgen';

export default defineConfig({
  plugins: [
    pluginApiDocgen({
      entries: {
        button: './src/index.ts',
      },
      apiParseTool: 'react-docgen-typescript',
    }),
  ],
});

      然后你可以在 MDX 中使用 API 组件将 API 内容注入到文档中：

      ## API

这是 API 表格

<API moduleName="button" />

      配置

      这个插件接受一个对象参数，类型如下:

      interface Options {
  entries?: Record<string, string>;
  apiParseTool?: 'react-docgen-typescript' | 'documentation';
  appDir?: string;
  parseToolOptions?: ParseToolOptions;
}

      appDir

      appDir用来配置插件解析文件的基准目录，默认为 process.cwd()

      entries

      entries 用来配置解析文件的基本信息：

      • key 为标识符，作为 API 组件的 moduleName属性
      • value 为解析文件的相对路径

      apiParseTool

      apiParseTool 用来选择解析工具，默认为react-docgen-typescript：

      • react-docgen-typescript针对于组件库场景，仅会解析 props 生成表格。
      export type ButtonProps = {
  /**
   * Whether to disable the button
   */
  disabled?: boolean;
  /**
   * Type of Button
   * @default 'default'
   */
  size?: 'mini' | 'small' | 'default' | 'large';
};
export const Button = (props?: ButtonProps) => {};

      上面是一个标准写法，其中 ButtonProps 将被提取至表格中， Button 作为表格的标题。 如果使用默认导出，文件名将作为表格标题。

      需要注意的是，export 导出事先定义的特性将不会被解析。

      const A = () => {};

export { A }; // wrong
export default A; // wrong
export const B = () => {}; // right
export default () => {}; // right

      生成的内容如下：

      ### ButtonTest

|   属性   |             说明              |                    类型                     |   默认值    |
| :------: | :---------------------------: | :-----------------------------------------: | :---------: |
| disabled | Whether to disable the button |                  `boolean`                  |     `-`     |
|   size   |        Type of Button         | `"mini" \| "small" \| "default" \| "large"` | `'default'` |
      Warning

      如果 Props 里使用了 React 的类型，你需要在 tsconfig.json 里添加 types ，否则会解析不到 React 命名空间下的类型。

      {
  "compilerOptions": {
    "types": ["react"]
  }
}

      更好的方式是直接引用类型，例如

      import { FC } from 'react';
      • documentation适用于工具库场景，用来解析 JSDoc 注释。 下面是一个带有 JSDoc 注释的 greet 函数。
      /**
 * Greet function that returns a greeting message.
 * @param {string} name - The name of the person to greet.
 * @param {string} [greeting='Hello'] - The greeting to use.
 * @returns {string} The greeting message.
 */
function greet(name: string, greeting = 'Hello') {
  return `${greeting}, ${name}!`;
}

      上面是一个带有 JSDoc 注释的 greet 函数。生成的内容如下：

      <!-- Generated by documentation.js. Update this documentation by updating the source code. -->

## greet

Greet function that returns a greeting message.

### Parameters

- `name` **[string][1]** The name of the person to greet.
- `greeting` **[string][1]** The greeting to use. (optional, default `'Hello'`)

Returns **[string][1]** The greeting message.

[1]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String

      parseToolOptions

      parseToolOptions 用来传入对应解析器的参数，其类型如下：

      type ParseToolOptions = {
  'react-docgen-typescript'?: ParserOptions & {
    tsconfigPath?: Record<string, string>;
    compilerOptions?: Record<string, ts.CompilerOptions>;
  };
  documentation?: DocumentationArgs;
};

      请参考 ParserOptions 和 DocumentationArgs 了解可用选项。

      如果解析器是 react-docgen-typescript，默认使用 withDefaultConfig 方法创建解析器实例，如果配置了 tsconfigPath 或 compilerOptions 则会分别使用 withCompilerOptions 和 withCustomConfig 方法创建解析器实例，tsconfigPath 和 compilerOptions可以分别针对每个 entry 设置，详情查看 Custom Parsers。