# Архитектура документации 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  <!-- ⛔ LEGACY: registry.kube5s.ru ЗАКРЫТ. Актуальный хост: tf-registry.containerk8s.services.ngcloud.ru -->  <!-- ⛔ LEGACY: registry.kube5s.ru  <!-- ⛔ LEGACY: registry.kube5s.ru ЗАКРЫТ. Актуальный хост: tf-registry.containerk8s.services.ngcloud.ru --> ЗАКРЫТ. Актуальный хост: tf-registry.containerk8s.services.ngcloud.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 ===
<содержимое>
...
```

### Формат выхода
```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, что делает параметр.** Это должно быть максимально понятно.

## Сборка mkdocs: слияние статического и динамического nav

mkdocs-material не имеет встроенного `!include` для `nav:`. Решение (рекомендовано): расширить Python pre-build шаг в `04_build_and_publish_docs.sh`:

1. `WriteNavFragment()` генерирует `_nav_fragment.yml` с `resources_nav:` (категории + ресурсы)
2. Python-блок читает `_nav_fragment.yml`, парсит `mkdocs.yml`, вставляет ресурсы в секцию `Ресурсы` внутри `nav:`
3. Одновременно копирует `30_registry/` в `docs_dir` (чтобы guides не ломались при смене `docs_dir`)
4. Результат пишется в `.mkdocs.tmp.yml` → `mkdocs build -f .mkdocs.tmp.yml`

Альтернативы (отвергнуты):
- docs-generator пишет полный mkdocs.yml (слишком хрупко)
- mkdocs-awesome-pages (не решает проблему merge static+dynamic)