@rspress/plugin-api-docgen
Исходный код

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

Установка

npm

yarn

pnpm

bun

deno

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

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

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

// 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 будет использовано как заголовок таблицы. Если вы используете экспорт по умолчанию (export default), то в качестве заголовка таблицы будет взято имя файла.

Обратите внимание: экспорты, объявленные не в том же файле, не поддерживаются.

const A = () => {};

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

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

### ButtonTest

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

Предупреждение

Если в Props используются типы React (например, React.ReactNode, React.FC и т. д.), необходимо добавить эти типы в tsconfig.json, иначе они не будут найдены в пространстве имён React.

{
  "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, то tsconfigPath и compilerOptions можно установить отдельно для каждого entry; в этом случае для создания экземпляра парсера используются методы withCompilerOptions и withCustomConfig соответственно. Подробности см. в разделе Custom Parsers.

#@rspress/plugin-api-docgen Исходный код

#Установка

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

#Конфигурация

#appDir

#entries

#apiParseTool

#parseToolOptions