#@rspress/plugin-api-docgen

Исходный код

Этот плагин автоматически генерирует контент документации API, используя пакеты react-docgen-typescript и documentation.

#Установка

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

#Использование

Сначала добавьте следующую конфигурацию:

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

Затем используйте компонент API для вставки документации API в файл MDX:

## 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 настраивает файлы для парсинга.

• Ключ — это идентификатор, используемый как атрибут moduleName компонента API.
• Значение — относительный путь к парсируемому файлу.

#apiParseTool

apiParseTool выбирает парсер. По умолчанию используется react-docgen-typescript:

• react-docgen-typescript используется для сценариев библиотек компонентов. Он парсит пропсы для генерации таблиц.

export type ButtonProps = {
  /**
   * Отключена ли кнопка?
   */
  disabled?: boolean;
  /**
   * Тип кнопки
   * @default 'default'
   */
  size?: 'mini' | 'small' | 'default' | 'large';
};
export const Button = (props?: ButtonProps) => {};

В этой стандартной форме ButtonProps извлекается в таблицу, а Button используется как заголовок таблицы. Если вы используете экспорт по умолчанию, в качестве заголовка таблицы используется имя файла.

Обратите внимание, что экспорты, объявленные в других местах, недоступны.

const A = () => {};

export { A }; // неправильно
export default A; // неправильно
export const B = () => {}; // правильно
export default () => {}; // правильно

Сгенерированный контент будет выглядеть следующим образом:

### ButtonTest

|   Проп   |      Описание       |                     Тип                     | Значение по умолчанию |
| :------: | :-----------------: | :-----------------------------------------: | :-------------------: |
| disabled | Отключена ли кнопка |                  `boolean`                  |          `-`          |
|   size   |    Размер кнопки    | `"mini" \| "small" \| "default" \| "large"` |      `'default'`      |

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

import { FC } from 'react';

• documentation используется в сценариях утилитарных библиотек для парсинга аннотаций JSDoc. Вот функция greet с аннотациями JSDoc.

/**
 * Функция приветствия, возвращающая приветственное сообщение.
 * @param {string} name - Имя человека, которого нужно поприветствовать.
 * @param {string} [greeting='Привет'] - Приветствие, которое будет использовано.
 * @returns {string} Приветственное сообщение.
 */
function greet(name: string, greeting = 'Привет') {
  return `${greeting}, ${name}!`;
}

Сгенерированный контент будет выглядеть следующим образом:

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

## greet

Функция приветствия, возвращающая приветственное сообщение.

### Parameters

- `name` **[string][1]** Имя человека, которого нужно поприветствовать.
- `greeting` **[string][1]** Приветствие, которое будет использовано. (optional, default `'Hello'`)

Returns **[string][1]** Приветственное сообщение.

[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, их можно задать отдельно для каждой entry; withCompilerOptions и withCustomConfig используются для создания экземпляра парсера соответственно. Подробности смотрите в Custom Parsers.