@rspress/plugin-api-docgen#

The plugin is used to generate api document description automatically, powered by react-docgen-typescript and documentation.

Install#

npm add @rspress/plugin-api-docgen -D

Usage#

First of all, you need to add following config:

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

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

Then you can use API component to inject api documentation to your mdx file:

## API

This is API Table

<API moduleName="button" />

Config#

The plugin accepts an object, which has the following types:

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

appDir#

appDir is used to configure the base directory for parsing，default process.cwd().

entries#

entries is used to configure the basic info for parsing.

• key is an identifier that serves as the moduleName attribute of the API component.
• value is the relative path to the parsed file.

apiParseTool#

apiParseTool is used to choose the tool for parsing，default react-docgen-typescript:

• react-docgen-typescriptis used for component library scenarios, only props will be parsed to generate tables.

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) => {};

The above is a standard writeup where ButtonProps will be extracted into the form and Button will be used as the form title. If you use the default export, the filename will be used as the form title.

Notice that export features declared elsewhere are not available.

const A = () => {};

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

The generated content is as follows:

### ButtonTest

|  Props   |          Description          |                    Type                     |   Default   |
| :------: | :---------------------------: | :-----------------------------------------: | :---------: |
| disabled | Whether to disable the button |                  `boolean`                  |     `-`     |
|   size   |        Type of Button         | `"mini" \| "small" \| "default" \| "large"` | `'default'` |

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

import { FC } from 'react';

• documentation is used in tool library scenarios to parse JSDoc annotations. Here is a greet function with JSDoc annotations.

/**
 * 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}!`;
}

The generated content is as follows:

<!-- 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 is used to pass options to the corresponding parse tool, whose types are as follows:

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

Please refer to ParserOptions and DocumentationArgs to learn about available options.

If the parser is react-docgen-typescript, the withDefaultConfig method is used by default to create a parser instance. If tsconfigPath or compilerOptions is configured, tsconfigPath and compilerOptions can be set separately for each entry, the withCompilerOptions and withCustomConfig methods are used to create the parser instance respectively. See Custom Parsers for details.