diff --git a/docs/LLM_DOCS_GENERATION.md b/docs/LLM_DOCS_GENERATION.md index 0214cb7..aaba9e6 100644 --- a/docs/LLM_DOCS_GENERATION.md +++ b/docs/LLM_DOCS_GENERATION.md @@ -1,86 +1,100 @@ -# LLM-генерация документации (120B) +# Архитектура документации Nubes Terraform Provider -## Идея +## Источники истины -Вместо шаблонного `docs-generator` (который просто раскладывает YAML по таблицам), использовать LLM для генерации человекочитаемой документации с пониманием контекста. +| Уровень | Источник | Роль | +|---|---|---| +| 1 | **API (YAML-спеки)** | Единственный источник правды. Параметры, типы, defaults, constraints, operations — только из YAML | +| 2 | **MAN (service_man)** | Дополнительный контекст. Может устареть или содержать ошибки. Используется для улучшения формулировок, но НЕ переопределяет YAML | +| 3 | **LLM (gpt-oss-120b)** | Обрабатывает .md файлы: улучшает читаемость, добавляет логику, переводит HTML→Markdown. Меняет ТОЛЬКО текст описаний, НЕ параметры | -## Модель - -`gpt-oss-120b` через API `api.aillm.ru`. - -## Как работает - -1. `yaml-generator` получает полный YAML-спек сервиса из API Nubes -2. YAML (все операции, параметры, подсвойства map-fixed, MAN) подаётся LLM -3. LLM генерирует Markdown-страницу документации -4. Результат сохраняется в `docs/30_registry/resources/{service}.md` - -## Универсальный промпт +## Пайплайн генерации ``` -Ты — генератор документации Terraform-провайдера Nubes Cloud. -Отвечай ТОЛЬКО Markdown-кодом. - -⛔ ЖЁСТКИЕ ПРАВИЛА (нарушать нельзя): - -1. НЕ ВЫДУМЫВАЙ параметры. Только те, что есть в YAML. - Если у параметра нет description — напиши "—". - НИКОГДА не придумывай password, role, encoding и т.п. - -2. Action-операции. ТОЛЬКО redeploy включается в документацию. - restart, recovery, reconcile — ИСКЛЮЧИТЬ. - -3. Subresource-операции. Каждый subresource → отдельная секция. - Имя ресурса: nubes_{service}_{subresource}. - -4. Lifecycle. suspend_on_destroy=true → "terraform destroy = Suspend". - adopt_existing_on_create → "terraform apply может подхватить существующий". - -5. Outputs. Все поля из outputs.params. vault_secrets помечать как 🔒. - -6. MAN. Если service_man есть — вставить как есть в секцию ## MAN. - -ФОРМАТ: -# Resource nubes_{name} -## MAN (если есть) -## Instance Operations (таблица) -## Create Parameters (таблица) -## Subresources (таблица по каждому) -## Lifecycle -## Outputs (таблица) - -YAML-спек: -```yaml -{содержимое YAML-файла} -``` +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 ``` -## Результаты тестирования (PostgreSQL) +## Структура страниц (на каждый сервис) -| Критерий | Результат | +| Файл | Содержание | |---|---| -| Выдуманные параметры | ❌ 0 (было: password, roles, encoding) | -| Action-операции исключены | ✅ restart/recovery/reconcile | -| Subresources | ✅ user, database, backup | -| Параметры из YAML | ✅ username, role, dbName, dbOwner | -| Допустимые значения | ✅ app_user/ddl_user | -| Regex-ограничения | ✅ ^[A-Za-z0-9]+$ | -| Outputs | ✅ все 8 полей | -| Lifecycle | ✅ suspend_on_destroy=true | +| `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) -- `map-fixed` параметры описываются как "составной параметр" без подсвойств -- Нужен Jenkins-ендпоинт для получения sub_fields для map-fixed -- С полными данными оценка будет 10/10 +- `max-width: 1800px` — лёгкое ограничение (на 2560px поля ~380px) +- 🔵 Синий — переменные верхнего уровня (структуры) +- 🟢 Зелёный — поля внутри структур (sub_params) +- ID — мелкий, серый (техническая информация) +- Default — заметный (юзеру важно что будет если не указать) +- Description/Constraints — мелкий серый (доп. информация) +- Без переносов в коде, description — с переносами -## Интеграция в пайплайн +## Сервисы с подробным MAN (для LLM-обработки) -Предлагаемое место — после `01_generate_yamls.sh`, вместо текущего `02_generate_resources_and_docs_v2.sh` для docs-части: +| Сервис | MAN (символов) | +|---|---| +| rabbitmq | 9811 | +| mongodb | 9296 | +| postgres | 8252 | +| gitea | 6639 | +| clickhouse | 6010 | +| flask | 5569 | +| kafka | 5210 | +| vapp | 4659 | +| akhq | 3838 | +## LLM-промпт (на один сервис) + +LLM получает ВСЕ .md файлы сервиса + ключевые поля из YAML + MAN и переписывает их. + +### Формат входа ``` -01_generate_yamls.sh → YAML - ↓ - LLM-генератор → Markdown-доки - resource-generator → Go-ресурсы +Сервис: +YAML (ключевое): параметры, типы, defaults, constraints +MAN: +Файлы: +=== Name.md === +<содержимое> +... ``` + +### Формат выхода +```json +{ + "Name.md": "полный текст", + "Name_example.md": "полный текст", + ... +} +``` + +### Правила для LLM +1. **YAML = истина. MAN = контекст.** Если противоречат → верить YAML. +2. HTML-таблицы: менять ТОЛЬКО текст внутри ``, НЕ трогать структуру тегов. +3. HCL-блоки: НЕ трогать. +4. Navigation-строки: НЕ трогать. +5. Имена ресурсов (nubes_*): НЕ менять. +6. MAN-секцию: перевести из HTML в читаемый Markdown. +7. Описания: сделать грамотными, логичными, на русском. Добавить контекст из MAN где уместно. +8. **Юзер в первую очередь смотрит на: имя переменной, required/default, что делает параметр.** Это должно быть максимально понятно.