#@rspress/plugin-api-docgen

Source Code

This plugin generates API reference content automatically, powered by react-docgen-typescript and documentation.

#Install

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

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

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

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

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

#Usage

First, add the following configuration:

// 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',
    }),
  ],
});

Then use the API component to inject API documentation into an MDX file:

## API

This is API Table

<API moduleName="button" />

#Internationalization

This plugin uses the plugin API i18nSource to add the following translations:

// cspell:disable
export const apiDocgenI18n = {
  apiDocgenProperty: {
    en: 'Property',
    zh: '属性',
    ja: 'プロパティ',
    ko: '속성',
    ru: 'Свойство',
    ta: 'பண்பு',
  },
  apiDocgenDescription: {
    en: 'Description',
    zh: '说明',
    ja: '説明',
    ko: '설명',
    ru: 'Описание',
    ta: 'விளக்கம்',
  },
  apiDocgenType: {
    en: 'Type',
    zh: '类型',
    ja: '型',
    ko: '타입',
    ru: 'Тип',
    ta: 'வகை',
  },
  apiDocgenDefaultValue: {
    en: 'Default Value',
    zh: '默认值',
    ja: 'デフォルト値',
    ko: '기본값',
    ru: 'Значение по умолчанию',
    ta: 'இயல்புநிலை மதிப்பு',
  },
  apiDocgenRequired: {
    en: 'Required',
    zh: '必填',
    ja: '必須',
    ko: '필수',
    ru: 'Обязательно',
    ta: 'கட்டாயம்',
  },
  apiDocgenClassName: {
    en: 'Additional css class',
    zh: '节点类名',
    ja: '追加の CSS クラス',
    ko: '추가 CSS 클래스',
    ru: 'Имя класса узла',
    ta: 'கூடுதல் CSS வகுப்பு',
  },
  apiDocgenStyle: {
    en: 'Additional style',
    zh: '节点样式',
    ja: '追加のスタイル',
    ko: '추가 스타일',
    ru: 'Стиль узла',
    ta: 'கூடுதல் பாணி',
  },
  apiDocgenChildren: {
    en: 'Children',
    zh: '子节点',
    ja: '子要素',
    ko: '자식 요소',
    ru: 'Дочерние элементы',
    ta: 'உள்ளடக்கம்',
  },
  apiDocgenDisabled: {
    en: 'Whether to disable ',
    zh: '是否禁用',
    ja: '無効にするかどうか',
    ko: '비활성화 여부',
    ru: 'Отключено',
    ta: 'முடக்க வேண்டுமா',
  },
};

You can override these texts with the user configuration i18nSource.

#Config

The plugin accepts an object with the following type:

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

#appDir

appDir configures the base directory for parsing. The default is process.cwd().

#entries

entries configures the files to parse.

• The key is an identifier used as the moduleName attribute of the API component.
• The value is the relative path to the file being parsed.

#apiParseTool

apiParseTool selects the parser. The default is react-docgen-typescript:

• react-docgen-typescript is used for component library scenarios. It parses props 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) => {};

In this standard form, ButtonProps is extracted into a table and Button is used as the table title. If you use a default export, the file name is used as the table title.

Note that exports 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 utility 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 passes options to the selected parser. Its type is:

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

See ParserOptions and DocumentationArgs for available options.

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