tf_provider/docs/LLM_DOCS_GENERATION.md

Архитектура документации Nubes Terraform Provider

Источники истины

Уровень	Источник	Роль
1	API (YAML-спеки)	Единственный источник правды. Параметры, типы, defaults, constraints, operations — только из YAML
2	MAN (service_man)	Дополнительный контекст. Может устареть или содержать ошибки. Используется для улучшения формулировок, но НЕ переопределяет YAML
3	LLM (gpt-oss-120b)	Обрабатывает .md файлы: улучшает читаемость, добавляет логику, переводит HTML→Markdown. Меняет ТОЛЬКО текст описаний, НЕ параметры

Пайплайн генерации

YAML-спеки
    │
    ▼
docs-generator (Go) ─── создаёт структуру: Name.md, Name_example.md, Name_params_create.md, ...
    │                    HCL-блоки, HTML-таблицы параметров, navigation, index.md
    ▼
LLM (gpt-oss-120b) ─── улучшает описания: читаемый Markdown, логичные формулировки
    │                    вход: YAML + MAN + текущие .md
    │                    выход: переписанные .md (структура и параметры неизменны)
    ▼
mkdocs-material ─────── собирает статический сайт
    │
    ▼
S3 (terraform-registry) ── хостинг через registry.kube5s.ru

Структура страниц (на каждый сервис)

Файл	Содержание
Name.md	Главная: MAN (переведён в Markdown), навигация
Name_example.md	HCL-пример с полным манифестом
Name_params_create.md	Таблицы Create-параметров + вложенные sub_params
Name_params_modify.md	Таблицы Modify-параметров
Name_outputs.md	Выходные параметры + реальные ключи из облака
Name_ops.md	Список операций (create/delete/modify/suspend/resume)
Name_params.md	Лендинг: ссылки на create/modify params
Name_subresource.md	Для каждого subresource: параметры
Name_subresource_example.md	HCL-пример subresource

Принципы дизайна (CSS)

• max-width: 1800px — лёгкое ограничение (на 2560px поля ~380px)
• 🔵 Синий — переменные верхнего уровня (структуры)
• 🟢 Зелёный — поля внутри структур (sub_params)
• ID — мелкий, серый (техническая информация)
• Default — заметный (юзеру важно что будет если не указать)
• Description/Constraints — мелкий серый (доп. информация)
• Без переносов в коде, description — с переносами

Сервисы с подробным MAN (для LLM-обработки)

Сервис	MAN (символов)
rabbitmq	9811
mongodb	9296
postgres	8252
gitea	6639
clickhouse	6010
flask	5569
kafka	5210
vapp	4659
akhq	3838

LLM-промпт (на один сервис)

LLM получает ВСЕ .md файлы сервиса + ключевые поля из YAML + MAN и переписывает их.

Формат входа

Сервис: <service_name>
YAML (ключевое): параметры, типы, defaults, constraints
MAN: <service_man>
Файлы:
=== Name.md ===
<содержимое>
...

Формат выхода

{
  "Name.md": "полный текст",
  "Name_example.md": "полный текст",
  ...
}

Правила для LLM

1. YAML = истина. MAN = контекст. Если противоречат → верить YAML.
2. HTML-таблицы: менять ТОЛЬКО текст внутри <td>, НЕ трогать структуру тегов.
3. HCL-блоки: НЕ трогать.
4. Navigation-строки: НЕ трогать.
5. Имена ресурсов (nubes_*): НЕ менять.
6. MAN-секцию: перевести из HTML в читаемый Markdown.
7. Описания: сделать грамотными, логичными, на русском. Добавить контекст из MAN где уместно.
8. Юзер в первую очередь смотрит на: имя переменной, required/default, что делает параметр. Это должно быть максимально понятно.