Integ Docs | API

Appearance

Руководство по написанию документации ​

Стандарты и правила для создания консистентной и читаемой документации проекта Integ.

Структура документации ​

docs/
├── index.md                    # Главная страница (VitePress hero)
├── getting-started/            # Быстрый старт для новичков
│   ├── index.md               # Обзор и навигация
│   ├── first-setup.md         # Первоначальная настройка (одноразово)
│   ├── installation.md        # Установка зависимостей
│   └── configuration.md       # Конфигурация окружения
├── guides/                     # Руководства по работе
│   ├── index.md               # Обзор руководств
│   ├── daily-workflow.md      # Ежедневный workflow разработчика
│   └── common-errors.md       # Частые ошибки и решения
├── architecture/               # Архитектура системы
│   ├── index.md               # Обзор архитектуры
│   ├── modules.md             # Описание модулей
│   ├── patterns.md            # Паттерны и соглашения
│   └── business-logic.md      # Бизнес-логика и потоки данных
├── api-guide/                  # Справочник по API
│   ├── index.md               # Обзор API
│   ├── authentication.md      # Аутентификация
│   ├── integrations.md        # CRUD интеграций
│   ├── secrets.md             # Управление секретами
│   └── ...                    # Другие API
├── integrations/               # Документация конкретных интеграций
│   ├── _template.md           # Шаблон для новой интеграции
│   ├── telegram.md            # Telegram интеграция
│   └── ...                    # Другие интеграции
├── packages/                   # Документация пакетов
│   ├── _template.md           # Шаблон для нового пакета
│   ├── integ-core.md          # integ-core пакет
│   └── ...                    # Другие пакеты
├── deployment/                 # Деплой и инфраструктура
│   ├── index.md               # Обзор деплоя
│   ├── docker.md              # Docker конфигурация
│   └── environments.md        # Окружения (local/dev/prod)
├── development/                # Разработка
│   ├── index.md               # Обзор инструментов
│   ├── code-rules.md          # Правила написания кода
│   ├── git-workflow.md        # Git workflow
│   └── testing.md             # Тестирование
└── contributing/               # Участие в проекте
    ├── DOCUMENTATION_GUIDE.md # Это руководство
    └── CHANGELOG.md           # История изменений

Форматирование ​

Заголовки ​

markdown
# Название документа (H1) - только один на файл

## Основные разделы (H2)

### Подразделы (H3)

#### Детали (H4) - использовать редко

Списки ​

markdown
## Нумерованные - для последовательных шагов

1. Первый шаг
2. Второй шаг
3. Третий шаг

## Маркированные - для перечислений

- Элемент списка
- Другой элемент
- Ещё элемент

Код ​

markdown
## Inline код

Используйте `npm install` для установки.

## Блоки кода с подсветкой

```bash
npm install
npm start
```

```typescript
const user = await usersService.findOne({ where: { id } });
```

```json
{
	"name": "example",
	"version": "1.0.0"
}
```

VitePress компоненты ​

markdown
::: tip Совет
Полезная информация для улучшения опыта.
:::

::: info Информация
Дополнительный контекст или пояснение.
:::

::: warning Внимание
Важное предупреждение о возможных проблемах.
:::

::: danger Опасно
Критическое предупреждение - несоблюдение может привести к проблемам.
:::

::: details Подробности (раскрывающийся блок)
Скрытый контент, который можно раскрыть.
:::

Диаграммы (Mermaid) ​

markdown
```mermaid
graph LR
    A[Клиент] --> B[API]
    B --> C[База данных]
```

```mermaid
sequenceDiagram
    participant C as Client
    participant A as API
    participant D as Database

    C->>A: Request
    A->>D: Query
    D-->>A: Result
    A-->>C: Response
```

Структура документа ​

Стандартный шаблон страницы ​

markdown
# Название

Краткое описание (1-2 предложения) что это и зачем нужно.

## Обзор

Более подробное описание с контекстом.

## Основной контент

### Подраздел 1

Контент...

### Подраздел 2

Контент...

## Примеры

Практические примеры использования.

## Troubleshooting

Частые проблемы и их решения (опционально).

## Связанные документы

- [Документ 1](./link1.md)
- [Документ 2](./link2.md)

API эндпоинт ​

markdown
### METHOD /api/endpoint

Краткое описание что делает эндпоинт.

**Параметры:**

| Параметр | Тип    | Обязательный | Описание            |
| -------- | ------ | ------------ | ------------------- |
| id       | string | Да           | Идентификатор       |
| name     | string | Нет          | Название (optional) |

**Request:**

\`\`\`http
POST /api/endpoint
Authorization: Bearer <token>
Content-Type: application/json

{
"name": "example"
}
\`\`\`

**Response (200 OK):**

\`\`\`json
{
"id": "uuid",
"name": "example",
"createdAt": "2024-01-01T00:00:00.000Z"
}
\`\`\`

**Ошибки:**

| Код | Описание           |
| --- | ------------------ |
| 400 | Неверные параметры |
| 401 | Не авторизован     |
| 404 | Ресурс не найден   |
| 500 | Внутренняя ошибка  |

Шаблон для интеграции ​

Смотри _template.md - полный шаблон для документирования новой интеграции.

Обязательные секции:

  1. Обзор - что это за интеграция
  2. Требования - что нужно для работы
  3. Установка - как настроить
  4. Конфигурация - переменные и секреты
  5. API Reference - доступные методы
  6. Примеры - практическое использование
  7. Troubleshooting - частые проблемы

Шаблон для пакета ​

Смотри _template.md - полный шаблон для документирования нового пакета.

Обязательные секции:

  1. Обзор - назначение пакета
  2. Установка - как подключить
  3. API Reference - экспортируемые функции/классы
  4. Примеры - использование
  5. Changelog - история версий

Языковые соглашения ​

Язык документации ​

  • Основной язык: Русский
  • Код и команды: Английский
  • Названия переменных/функций: Английский

Стиль написания ​

  • Используйте настоящее время: "Создаёт пользователя", не "Создаст пользователя"
  • Активный залог: "Сервис обрабатывает запрос", не "Запрос обрабатывается сервисом"
  • Краткость: Избегайте лишних слов
  • Конкретность: Приводите примеры вместо абстрактных описаний

Терминология ​

ИспользуйтеНе используйте
ИнтеграцияИнтеграшка
ЭндпоинтЕндпоинт, endpoint
СекретСекретное значение
ТокенToken
ПользовательЮзер
КонфигурацияКонфиг

Правила для разных типов документов ​

Getting Started ​

  • Максимально простой язык
  • Пошаговые инструкции с номерами
  • Проверки после каждого шага
  • Минимум теории - только практика

Architecture ​

  • Диаграммы обязательны
  • Объяснение "почему", а не только "что"
  • Связи между компонентами
  • Trade-offs принятых решений

API Guide ​

  • Полные примеры запросов и ответов
  • Все параметры в таблице
  • Коды ошибок с описанием
  • cURL примеры для быстрого тестирования

Integrations ​

  • Quick start в начале
  • Полный пример в конце
  • Скриншоты где уместно
  • Ссылки на внешнюю документацию

Packages ​

  • Установка в начале
  • API Reference - все exports
  • TypeScript типы обязательны
  • Версионирование и changelog

Чеклист перед публикацией ​

  • [ ] Заголовок H1 соответствует содержанию
  • [ ] Есть краткое описание в начале
  • [ ] Код примеры проверены и работают
  • [ ] Все ссылки рабочие
  • [ ] Используется консистентная терминология
  • [ ] Есть раздел "Связанные документы"
  • [ ] Нет орфографических ошибок
  • [ ] VitePress preview работает корректно

Обновление документации ​

Когда обновлять ​

  • При изменении API
  • При добавлении новых функций
  • При изменении конфигурации
  • При обнаружении ошибок в документации

Процесс ​

  1. Найти соответствующий файл
  2. Внести изменения
  3. Проверить через npm run docs:dev
  4. Создать PR с описанием изменений

Полезные команды ​

bash
# Запустить локальный сервер документации
npm run docs:dev

# Собрать для production
npm run docs:build

# Предпросмотр production сборки
npm run docs:preview

Обновлено: