Написание документации

Сайт документации построен на Docusaurus и находится в каталоге website/ репозитория cpr1c/tools_ui_1c.

Требования

Перед началом работы убедитесь, что установлено:

Компонент	Версия	Ссылка
Node.js	>= 20.0	nodejs.org
npm	поставляется с Node.js	—
Git	любая	git-scm.com

Проверить установку:

node --version   # >=20.0
npm --version
git --version

Быстрый старт

git clone https://github.com/cpr1c/tools_ui_1c.git
cd tools_ui_1c/website
npm install
npm start

Сайт откроется на http://localhost:3000. Любые изменения в website/docs/ и website/src/pages/ подхватываются автоматически (hot reload).

Как работает документация

Документация проекта построена на Docusaurus — современной платформе для создания сайтов документации. Вся документация находится в каталоге website/docs/ и написана в формате MDX — расширении Markdown с возможностью использовать JSX-компоненты.

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

website/docs/
├── intro.mdx                  # Введение (обязательный файл)
├── guides/                    # Руководства (установка, отладка, сборка…)
│   ├── _category_.json        # Обязательный файл для категории
│   └── *.mdx                  # Файлы руководств (installation.mdx, debugging.mdx и т.д.)
├── api/                       # Программный интерфейс
│   ├── _category_.json        # Обязательный файл для категории
│   └── *.mdx                  # Файлы API (code-editor.mdx, serialization.mdx и т.д.)
├── tools/                     # Описания инструментов по разделам
│   ├── _category_.json        # Обязательный файл для категории "Инструменты"
│   ├── development-tools/     # Подкатегория: инструменты разработки
│   │   ├── _category_.json    # Обязательный файл для подкатегории
│   │   ├── _index.mdx         # Панель инструментов (рекомендуется)
│   │   └── */                 # Индивидуальные инструменты
│   │       ├── intro.mdx      # Основной файл описания инструмента
│   │       └── img/           # Изображения инструмента
│   ├── data-tools/            # Подкатегория: работа с данными
│   └── ...                    # Другие подкатегории
└── contributing/              # Документация для контрибьюторов
    ├── _category_.json        # Обязательный файл для категории
    ├── documentation.mdx      # Написание документации (текущая статья)
    └── coding-guidelines.mdx  # Правила оформления кода

Пояснения:

• Каждая категория должна иметь файл _category_.json (кроме корневого уровня)
• Инструменты должны быть в подкаталогах с именем инструмента (kebab-case)
• Основной файл описания инструмента — intro.mdx
• Изображения инструмента — в img/ подкаталоге инструмента

Формат файлов

Документация пишется в формате MDX — Markdown с возможностью использовать JSX-компоненты.

---
sidebar_position: 1
---

# Заголовок страницы

Обычный текст с **разметкой** Markdown.

## Подзаголовок

- список
- пунктов

:::tip
Совет для читателя
:::

:::warning
Важное предупреждение
:::

Metadata (frontmatter)

Каждый MDX-файл начинается с блока ---, где указываются:

Поле	Описание
sidebar_position	Порядок в сайдбаре (1, 2, 3…)
description	Краткое описание для SEO

Где что писать

• Новый инструмент — создайте файл в соответствующем разделе docs/tools/*/, добавьте _category_.json для группировки
• Руководство — docs/guides/ (установка, отладка, сборка, миграция и т.д.)
• API — docs/api/

Ссылки

Внутренние ссылки — без расширения .mdx, от корня docs/:

[Установка](/docs/guides/installation)
[Консоль запросов](/docs/tools/development-tools/query-console)

Внешние ссылки — полный URL:

[GitHub](https://github.com/cpr1c/tools_ui_1c)

Изображения

Изображения размещайте в подкаталоге img/ рядом с файлом документации.

Правила размещения изображений для инструментов

1. Именование: tool-name-description.png (kebab-case)

   • code-console-overview.png — обзор консоли кода
   • query-console-result.png — результат консоли запросов

2. Размещение: website/docs/tools/*/img/

   • website/docs/tools/development-tools/code-console/img/ — изображения для консоли кода
   • website/docs/tools/data-tools/batch-processing/img/ — изображения для пакетной обработки

3. Размер: Оптимизируйте изображения (максимум 1-2 МБ)

4. Формат: PNG для скриншотов, SVG для иконок

Примеры ссылок на изображения

![Обзор консоли кода](./img/code-console-overview.png)

Универсальные изображения

Для универсальных изображений (логотипы, иконки) используйте website/static/img/:

![Логотип](/img/logo.svg)

Правила именования файлов и директорий

Для обеспечения согласованности и простоты поддержки документации соблюдайте следующие правила именования:

Имена директорий

• Используйте kebab-case: development-tools, data-tools, code-console
• Избегайте специальных символов, пробелов и кириллицы
• Имя директории должно соответствовать имени инструмента в коде

Имена файлов

• Используйте kebab-case для файлов: installation.mdx, debugging.mdx
• Основной файл описания инструмента — intro.mdx
• Изображения: tool-name-description.png (kebab-case)

Примеры правильного и неправильного

Правильно:

• code-console/ — директория для консоли кода
• intro.mdx — основной файл описания инструмента
• code-console-overview.png — изображение для консоли кода

Неправильно:

• CodeConsole/ — CamelCase вместо kebab-case
• КонсольКода/ — кириллица
• main.mdx — неинформативное имя
• img/overview.png — общий файл изображений

Организация новых инструментов в tools/

Структура category.json

Каждая категория в website/docs/tools/ должна иметь файл _category_.json со следующими полями:

{
  "label": "Название категории",
  "position": 1,
  "link": {
    "type": "generated-index",
    "title": "Описание категории",
    "description": "Полное описание того, что включает категория"
  }
}

Пояснения:

• label — отображаемое название категории в сайдбаре
• position — порядок категории (1, 2, 3...)
• link.type — тип генерируемого индекса (generated-index для автоматической генерации списка страниц)
• link.title — заголовок для индексной страницы
• link.description — описание для индексной страницы

Создание новой категории инструментов

1. Создайте директорию в website/docs/tools/ (например, new-feature/)
2. Создайте файл _category_.json с описанием категории
3. Создайте подкаталоги для инструментов (например, new-feature/tool-a/)
4. Для каждого инструмента создайте файл intro.mdx с описанием
5. Добавьте изображения в img/ подкаталог инструмента

Пример структуры новой категории

website/docs/tools/new-feature/
├── _category_.json            # Описание категории
├── _index.mdx                 # Панель категории (рекомендуется)
└── tool-a/                    # Инструмент A
    ├── intro.mdx              # Описание инструмента
    └── img/                   # Изображения
        └── tool-a-overview.png

Связь с исходным кодом

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

Как документировать новый инструмент

1. Определите источник: Найдите DataProcessor/Module в src/

   • src/Инструменты/src/DataProcessors/ — обработки
   • src/Инструменты/src/CommonModules/ — общие модули

2. Создайте документацию: Создайте структуру в website/docs/tools/*/

   • Директория с именем инструмента (kebab-case)
   • Файл intro.mdx с описанием

3. Укажите источник в документации:

   ## Назначение
   
   Инструмент позволяет выполнять чудо на регулярной основе. Реализован в обработке `УИ_ЧудоИнструмент`.

4. Добавьте ссылки в API документацию (если применимо):

   • Если инструмент имеет программный интерфейс, добавьте описание в website/docs/api/
   • Ссылки на API из документации инструмента

Шаблон создания нового инструмента

Пошаговый процесс

Шаг 1: Создание структуры

Создайте директории и файлы:

website/docs/tools/development-tools/new-tool/
├── _category_.json            # Если нужна новая подкатегория
├── intro.mdx                  # Основной файл описания
└── img/                       # Изображения
    └── new-tool-overview.png

Шаг 2: Описание инструмента

Создайте файл intro.mdx:

---
sidebar_position: 1
description: Описание инструмента для SEO. Добавьте ключевые слова как бы вы искали этот инструмент в поисковике
---

# Название инструмента

Краткое описание назначения инструмента.

![](./img/new-tool-overview.png)

## Назначение

Детальное описание назначения инструмента и его использования.

## Особенности

- Особенность 1
- Особенность 2
- Особенность 3

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

1. Шаг 1
2. Шаг 2
3. Шаг 3

## Программный интерфейс

Примеры использования API (если есть).

## Связанные разделы

- [Связанный инструмент](/docs/tools/...)
- [Руководство](/docs/guides/...)

Шаг 3: Проверка

1. Запустите локальный сервер: npm start
2. Проверьте отображение документации
3. Проверьте ссылки
4. Проверьте изображения

Проверочный список (checklist)

• Создана директория website/docs/tools/*/new-tool/
• Создан файл intro.mdx с описанием
• Создан файл _category_.json (если нужна новая категория)
• Добавлены изображения в img/
• Проверено отображение на локальном сервере
• Проверены все ссылки

Пример полной структуры инструмента

website/docs/tools/development-tools/new-tool/
├── _category_.json            # Если нужна новая подкатегория
├── intro.mdx                  # Основной файл описания
└── img/                       # Изображения
    ├── new-tool-overview.png
    ├── new-tool-details.png
    └── new-tool-settings.png

Комментарий: Следуя этому шаблону, добавление новых инструментов будет простым и предсказуемым процессом.

Полезные ссылки

• Docusaurus Documentation — официальная документация Docusaurus
• MDX Specification — спецификация MDX
• GitHub Repository — репозиторий проекта
• Telegram Chat — чат для обсуждения
• VK Chat — чат для обсуждения

Обновление сайдбара

Сайдбар настраивается в файле sidebars.ts в корне репозитория сайта. При добавлении новой страницы в существующую категорию (autogenerated) ничего менять не нужно. Для новой категории — добавьте запись вручную.

Pull Request

Перед открытием pull request ознакомьтесь с процессом Pull Request.

1. Внесите изменения в соответствующую ветку
2. Проверьте сборку: npm run build
3. Откройте PR в develop репозитория cpr1c/tools_ui_1c
4. После мержа сайт обновится автоматически

Советы

• Придерживайтесь единого стиля заголовков (с заглавной буквы)
• Используйте :::tip, :::warning, :::note для выделения важной информации
• Для примеров кода 1С используйте язык bsl в блоках:

  ```bsl
  Сообщить("Привет, мир!");
  ```

• Для bash-команд — bash