docs: LLM documentation architecture — truth sources, pipeline, CSS design, LLM prompt rules
This commit is contained in:
“Naeel”
+84
-70
@@ -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.
|
YAML-спеки
|
||||||
Отвечай ТОЛЬКО Markdown-кодом.
|
│
|
||||||
|
▼
|
||||||
⛔ ЖЁСТКИЕ ПРАВИЛА (нарушать нельзя):
|
docs-generator (Go) ─── создаёт структуру: Name.md, Name_example.md, Name_params_create.md, ...
|
||||||
|
│ HCL-блоки, HTML-таблицы параметров, navigation, index.md
|
||||||
1. НЕ ВЫДУМЫВАЙ параметры. Только те, что есть в YAML.
|
▼
|
||||||
Если у параметра нет description — напиши "—".
|
LLM (gpt-oss-120b) ─── улучшает описания: читаемый Markdown, логичные формулировки
|
||||||
НИКОГДА не придумывай password, role, encoding и т.п.
|
│ вход: YAML + MAN + текущие .md
|
||||||
|
│ выход: переписанные .md (структура и параметры неизменны)
|
||||||
2. Action-операции. ТОЛЬКО redeploy включается в документацию.
|
▼
|
||||||
restart, recovery, reconcile — ИСКЛЮЧИТЬ.
|
mkdocs-material ─────── собирает статический сайт
|
||||||
|
│
|
||||||
3. Subresource-операции. Каждый subresource → отдельная секция.
|
▼
|
||||||
Имя ресурса: nubes_{service}_{subresource}.
|
S3 (terraform-registry) ── хостинг через registry.kube5s.ru
|
||||||
|
|
||||||
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-файла}
|
|
||||||
```
|
|
||||||
```
|
```
|
||||||
|
|
||||||
## Результаты тестирования (PostgreSQL)
|
## Структура страниц (на каждый сервис)
|
||||||
|
|
||||||
| Критерий | Результат |
|
| Файл | Содержание |
|
||||||
|---|---|
|
|---|---|
|
||||||
| Выдуманные параметры | ❌ 0 (было: password, roles, encoding) |
|
| `Name.md` | Главная: MAN (переведён в Markdown), навигация |
|
||||||
| Action-операции исключены | ✅ restart/recovery/reconcile |
|
| `Name_example.md` | HCL-пример с полным манифестом |
|
||||||
| Subresources | ✅ user, database, backup |
|
| `Name_params_create.md` | Таблицы Create-параметров + вложенные sub_params |
|
||||||
| Параметры из YAML | ✅ username, role, dbName, dbOwner |
|
| `Name_params_modify.md` | Таблицы Modify-параметров |
|
||||||
| Допустимые значения | ✅ app_user/ddl_user |
|
| `Name_outputs.md` | Выходные параметры + реальные ключи из облака |
|
||||||
| Regex-ограничения | ✅ ^[A-Za-z0-9]+$ |
|
| `Name_ops.md` | Список операций (create/delete/modify/suspend/resume) |
|
||||||
| Outputs | ✅ все 8 полей |
|
| `Name_params.md` | Лендинг: ссылки на create/modify params |
|
||||||
| Lifecycle | ✅ suspend_on_destroy=true |
|
| `Name_subresource.md` | Для каждого subresource: параметры |
|
||||||
|
| `Name_subresource_example.md` | HCL-пример subresource |
|
||||||
|
|
||||||
## Ограничения
|
## Принципы дизайна (CSS)
|
||||||
|
|
||||||
- `map-fixed` параметры описываются как "составной параметр" без подсвойств
|
- `max-width: 1800px` — лёгкое ограничение (на 2560px поля ~380px)
|
||||||
- Нужен Jenkins-ендпоинт для получения sub_fields для map-fixed
|
- 🔵 Синий — переменные верхнего уровня (структуры)
|
||||||
- С полными данными оценка будет 10/10
|
- 🟢 Зелёный — поля внутри структур (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
|
Сервис: <service_name>
|
||||||
↓
|
YAML (ключевое): параметры, типы, defaults, constraints
|
||||||
LLM-генератор → Markdown-доки
|
MAN: <service_man>
|
||||||
resource-generator → Go-ресурсы
|
Файлы:
|
||||||
|
=== Name.md ===
|
||||||
|
<содержимое>
|
||||||
|
...
|
||||||
```
|
```
|
||||||
|
|
||||||
|
### Формат выхода
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"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, что делает параметр.** Это должно быть максимально понятно.
|
||||||
|
|||||||
Reference in New Issue
Block a user