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

Интеграция плагина TypeDoc для Rspress — автоматическая генерация документации API для модулей TypeScript.

Установка

npm

yarn

pnpm

bun

deno

npm add @rspress/plugin-typedoc -D

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

import { defineConfig } from '@rspress/core';
import { pluginTypeDoc } from '@rspress/plugin-typedoc';
import path from 'path';

export default defineConfig({
  plugins: [
    pluginTypeDoc({
      entryPoints: [
        path.join(__dirname, 'src', 'foo.ts'),
        path.join(__dirname, 'src', 'bar.ts'),
      ],
    }),
  ],
});

src/foo.ts

/**
 * Это функция сложения (add).
 */
export function add(
  /**
   * Это param1.
   */
  param1: string,
  /**
   * Это param2.
   */
  param2: number,
) {
  return 1;
}

src/bar.ts

/**
 * Это функция умножения (multi).
 */
export function multi(
  /**
   * Это param1.
   */
  param1?: string,
  /**
   * Это param2.
   */
  param2?: number,
) {
  return 1;
}

При запуске/сборке проекта плагин автоматически создаст папку api в корне вашей документации. Структура папки будет следующей:

api
├── _meta.json
├── index.md
├── functions
│   ├── bar.multi.md
│   └── foo.add.md
├── interfaces
│   ├── foo.RunTestsOptions.md
│   └── foo.TestMessage.md
└── modules
    ├── bar.md
    └── foo.md

Это означает, что плагин внутренне вызывает TypeDoc и автоматически генерирует документацию API для ваших модулей: списки модулей, детали Interface, детали функций (параметры, возвращаемые значения, описание) и т. д.

Обратите внимание, что файлы документации .md перегенерируются каждый раз при запуске проекта, чтобы отражать актуальное содержимое модулей. Поэтому мы рекомендуем добавить файлы .md в директории api в .gitignore, например: docs/api/**/*.md. Если вы настраиваете другую директорию вывода с помощью параметра outDir ниже, то соответствующие .md-файлы также следует добавить в .gitignore.

Файл _meta.json автоматически генерируется только при первом запуске и в дальнейшем не перезаписывается. Это позволяет вручную редактировать его для настройки структуры боковой панели (например, добавлять разделители, менять порядок и т. д.) и коммитить в git.

Мы не рекомендуем вручную изменять сгенерированные .md-документы в директории api, потому что эти документы будут перезаписываться каждый раз при запуске проекта из-за изменений в содержимом модулей.

Описание параметров

entryPoints

Тип: string[]
По умолчанию: []

Указывает абсолютные пути к модулям TypeScript, для которых нужно генерировать документацию.

outDir

Тип: string
По умолчанию: api

Позволяет задать собственную папку для вывода документации. Нужно указывать относительный путь, например api/custom.

setup

Тип: (app: Application) => Promise<Application> | Promise<void> | void
По умолчанию: () => {}

Функция для настройки приложения TypeDoc. Вы можете использовать её, чтобы изменить конфигурацию TypeDoc до того, как будет сгенерирована документация.

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

#Установка

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

#Описание параметров

#entryPoints

#outDir