terraform/tf_provider
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: Q&A with Sonnet — UX analysis + nav merge strategy (Phase 1-3 plan)

Browse Source
This commit is contained in:
“Naeel”
2026-08-10 13:32:09 +04:00
parent 35aa50f76d
commit 21b92f4631
4 changed files with 616 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
prompt_for_sonnet_docs_ux.md
+359
View File
@@ -0,0 +1,359 @@
# BRIEF: Анализ и рекомендации по документации Nubes Terraform Provider
**Для:** Claude Sonnet
**Дата:** 2026-08-10
**Задача:** Изучить ВЕСЬ пайплайн генерации документации, проанализировать фронтенд и UX, выдать подробные рекомендации по улучшению.
---
## 1. ЧТО ЭТО ТАКОЕ
Nubes Terraform Provider — это внутренний провайдер для Terraform, который управляет облачными сервисами (~43 сервиса: PostgreSQL, Redis, Kafka, S3, VMware и т.д.) через API платформы Nubes.
Документация — автосгенерированный статический сайт на mkdocs-material, который хостится в S3 и доступен юзерам провайдера.
**Юзер документации** — DevOps-инженер, который пишет Terraform-манифесты. Ему нужно:
1. Быстро найти нужный ресурс (сервис)
2. Понять какие параметры обязательные, какие опциональные, какие значения допустимы
3. Скопировать готовый HCL-пример и подставить свои значения
4. Узнать какие outputs можно использовать для связки ресурсов
5. Понять что делает каждая операция (create/modify/suspend/resume/...)
---
## 2. ПОЛНЫЙ ПАЙПЛАЙН ГЕНЕРАЦИИ
```
┌─────────────────────────────────────────────────────────────────┐
│ Шаг 1: YAML-спеки │
│ generated/{stand}/resources_yaml/{service}.yml │
│ ~43 YAML-файла: параметры, типы, defaults, constraints, MAN │
└──────────────────────────┬──────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Шаг 2: docs-generator (Go) │
│ TOOLS/docs-generator/main.go │
│ │
│ Вход: YAML + --version + --api-endpoint + --provider-source │
│ Выход: плоские .md файлы в generated/{stand}/docs_llm/ │
│ │
│ На каждый сервис генерирует: │
│ {name}.md — MAN (руководство пользователя) │
│ {name}_example.md — HCL-примеры (minimal + full) │
│ {name}_params_create.md — таблица create-параметров │
│ {name}_params_modify.md — таблица modify-параметров │
│ {name}_outputs.md — выходные параметры + cloud snapshot │
│ {name}_ops.md — список всех операций │
│ {name}_params.md — лендинг со ссылками │
│ index.md — общий индекс всех ресурсов │
│ _nav_fragment.yml — фрагмент для mkdocs sidebar │
│ │
│ Ключевые функции в writers/writers.go: │
│ ResourceDocs() — вызывает все build* функции │
│ buildCreateParamsPage() — таблицы обязательных/опциональных │
│ buildExamplePage() — minimal + full HCL примеры │
│ buildManualPage() — MAN: HTML → Markdown конвертация │
│ buildOutputsPage() — output params + cloud snapshot │
│ buildOpsPage() — список операций │
│ renderParamTable() — Markdown-таблица параметров │
│ renderNestedParams() — вложенные sub_params (map-fixed) │
│ IndexMD() — индекс всех ресурсов │
│ WriteNavFragment() — sidebar навигация │
│ │
│ Таблицы: Markdown (| Code | Type | ... |), НЕ HTML. │
│ Навигация: inline-строка в header каждой страницы: │
│ **Manual** · [Create params] · [Modify params] · ... │
│ (активная страница выделена жирным) │
└──────────────────────────┬──────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Шаг 3: LLM-обогащение (Python) │
│ TOOLS/scripts/05_generate_docs_llm.py │
│ │
│ LLM: gpt-oss-120b (через api.aillm.ru) │
│ На вход: все .md файлы сервиса + YAML + MAN │
│ На выход: переписанные .md (те же имена файлов) │
│ │
│ Что LLM делает: │
│ A. Переносит value_list из Constraints в Description │
│ "value_list=1,3,5" → "Допустимые значения: **1, 3, 5**" │
│ B. Преобразует regex в читаемый текст │
│ "regex=^[a-f0-9-]+$" → "Формат: UUID" │
│ C. Заполняет пустые Description (из MAN, имени параметра) │
│ D. Описывает map-fixed группы (из sub-params имён + MAN) │
│ E. Описывает операции без описания (suspend, resume, ...) │
│ F. Переводит HTML MAN в читаемый Markdown │
│ G. Заменяет TODO в примерах на реальные значения │
│ │
│ ЖЁСТКИЕ ЗАПРЕТЫ: │
│ - НЕ менять имена параметров │
│ - НЕ трогать HCL-блоки │
│ - НЕ трогать навигационные строки │
│ - НЕ менять структуру таблиц │
│ - НЕ выдумывать типы/defaults/constraints │
└──────────────────────────┬──────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Шаг 4: mkdocs-material (Python) │
│ mkdocs.yml + mkdocs build │
│ │
│ Тема: material, синяя схема │
│ Фичи: navigation.path, navigation.footer, navigation.indexes │
│ Markdown-расширения: md_in_html, admonition, superfences, ... │
│ CSS: extra.css — компактные шрифты, скрыты боковые панели │
│ JS: fix-slash.js — авто-добавление / в конец URL │
│ Выход: site/ — статический HTML │
└──────────────────────────┬──────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Шаг 5: S3 (s3cmd sync) │
│ s3://nubes-terraform-registry/docs/{stand}/{provider}/{ver}/ │
│ Доступ: https://tf-registry.containerk8s.services.ngcloud.ru/ │
│ docs/nubes-test/nubes/5.0.5/ │
└─────────────────────────────────────────────────────────────────┘
```
---
## 3. ТЕКУЩАЯ СТРУКТУРА ФРОНТЕНДА
### 3.1 Макет страницы ресурса
Каждая страница ресурса (например, PostgreSQL) имеет:
```
┌─────────────────────────────────────────────────────────┐
│ # Resource nubes_postgres · Service ID: 90 · PostgreSQL│
│ │
│ **Manual** · [Create params] · [Modify params] │
│ · [Output params] · [Operations] · [Example] │ ← inline nav
│ │
│ ## MAN │
│ (текст руководства — переведён из HTML в Markdown) │
│ ... │
└─────────────────────────────────────────────────────────┘
```
### 3.2 Что скрыто
CSS скрывает обе боковые панели mkdocs:
```css
.md-sidebar--primary { display: none !important; }
.md-sidebar--secondary { display: none !important; }
```
Это значит:
- **НЕТ sidebar-меню** — юзер не видит оглавление других ресурсов
- **НЕТ table of contents** — юзер не видит структуру текущей страницы
- Единственная навигация — inline-строка в header
### 3.3 CSS-особенности
- `font-size: 0.82rem` — компактный шрифт
- `max-width: 61rem` — умеренная ширина контента
- MAN-контент: `font-size: 0.62rem` — очень мелкий
- НЕТ стилей для Markdown-таблиц (были для HTML-таблиц `.resource-table`, теперь не применяются)
### 3.4 Индексная страница
Генерируется `IndexMD()` — простая таблица:
```
| ID | Ресурс | Описание |
|----|--------|----------|
| 1 | nubes_dummy | Болванка |
| 2 | nubes_template | Темплейт k8s |
...
```
Ссылки ведут на `{name}.md`.
---
## 4. ТЕКУЩИЕ ПРОБЛЕМЫ (ЧТО УЖЕ ИЗВЕСТНО)
### 4.1 Навигация — СЛАБОЕ МЕСТО №1
- Боковые панели скрыты → юзер теряется между страницами
- Inline-nav работает, но это неудобно: чтобы перейти к другому ресурсу, нужно вернуться на index
- Нет breadcrumbs между ресурсами (хотя mkdocs умеет `navigation.path`)
- Нет поиска по параметрам внутри ресурса
### 4.2 Таблицы параметров — СТАЛО ЛУЧШЕ
- Были HTML-таблицы, mkdocs их не рендерил → юзер видел голый текст `map-fixedmap-fixed`
- Исправлено: переведены на Markdown-таблицы → рендерятся корректно
- НО: стили `.resource-table` больше не применяются (они были для HTML)
- Описания параметров заполняются LLM, но не для всех (зависит от качества MAN)
### 4.3 Примеры (HCL) — работает
- Minimal example (только required) + Full example (с defaults) в раскрывашке `<details>`
- Юзер может скопировать и использовать
### 4.4 MAN-секция — перегружена
- `font-size: 0.62rem` — очень мелко, трудно читать
- HTML→Markdown конвертация в `htmlToMarkdown()` — regex-костыль, может глючить
- MAN содержит HTML из админки, его качество зависит от того, кто и как заполнял
### 4.5 Нет версионирования в интерфейсе
- Юзер не видит в UI какую версию провайдера он смотрит
- Хотя URL содержит версию (`/5.0.5/`), в самой странице это не отображается
---
## 5. ЧТО ХОРОШО (НЕ ЛОМАТЬ)
1. **Автоматическая генерация из YAML** — параметры всегда актуальны, не отстают от API
2. **Inline-навигация между страницами ресурса** — понятно где ты находишься
3. **Markdown-таблицы** — рендерятся везде, не зависят от HTML-санитайзеров
4. **LLM-обогащение** — описания становятся читаемыми (value_list, regex, пустые ячейки)
5. **Cloud snapshot в outputs** — реальные ключи `state_out_flat` и `vault_secrets` из облака
6. **Dual example** — minimal + full, юзер выбирает что нужно
---
## 6. ВОПРОСЫ К СОННЕТУ
### Блок A: Навигация и структура сайта
**A1.** Как организовать навигацию между ресурсами (43 сервиса)?
- Варианты: sidebar mkdocs, отдельная страница-индекс с поиском, grouped by category
- Плюсы/минусы каждого подхода для DevOps-юзера
**A2.** Нужно ли вернуть боковую панель mkdocs (sidebar)?
- Если да — что в ней должно быть: дерево ресурсов? категории? поиск?
- Если нет — как улучшить inline-nav + index page?
**A3.** Как юзер должен быстро найти нужный ресурс?
- Группировка: Базы данных, Очереди, Хранилище, K8s, VMware, Приложения, Сеть
- Поиск по имени/описанию?
### Блок B: Дизайн страницы ресурса
**B1.** MAN-секция сейчас `font-size: 0.62rem`. Как сделать читаемым?
- Оставить компактным но разборчивым?
- Сделать раскрывающимся (collapsed by default)?
- Вынести ключевую информацию выше?
**B2.** Как лучше структурировать страницу ресурса?
- Текущий порядок: Заголовок → Inline nav → MAN → ...
- Может: Заголовок → Краткое описание → Пример (сразу!) → Параметры → MAN (внизу)?
**B3.** Нужна ли версия провайдера в UI?
- Где показывать: в header? в title? в breadcrumb?
### Блок C: Таблицы параметров
**C1.** Как улучшить читаемость таблиц параметров?
- Сейчас: Code | Type | Description | Constraints
- Нужны ли: Required (yes/no), Default, категории параметров?
- Группировка связанных параметров (например, все cluster_configuration вместе)?
**C2.** Как показывать вложенные параметры (map-fixed)?
- Сейчас: ### clusterConfiguration → отдельная таблица sub_params
- Лучше: раскрывающийся блок? инлайн в той же таблице?
### Блок D: Примеры и HCL
**D1.** Как улучшить страницу Example?
- Сейчас: Minimal example сверху, Full example в `<details>`
- Добавить: описание каждого блока? комментарии в коде?
- Показывать реальные значения из облака?
### Блок E: Общие рекомендации
**E1.** Какие ещё элементы не хватает?
- Changelog между версиями?
- Ссылки на связанные ресурсы (PostgreSQL → как связать с Lucee/NodeJS)?
- Предупреждения/важные заметки (lifecycle behaviour)?
**E2.** Приоритизация: что сделать в первую очередь для максимального UX-эффекта?
---
## 7. КОНТЕКСТ ДЛЯ ИЗУЧЕНИЯ
### Файлы для чтения (в порядке важности):
1. **mkdocs.yml** — конфигурация сайта, тема, фичи, CSS
2. **TOOLS/docs-generator/internal/writers/writers.go** — ВСЯ генерация .md (~1000 строк, ключевой файл)
3. **TOOLS/docs-generator/main.go** — CLI, флаги, оркестрация
4. **TOOLS/scripts/05_generate_docs_llm.py** — LLM-обогащение, SYSTEM_PROMPT
5. **docs/LLM_DOCS_GENERATION.md** — архитектурная документация
6. **docs/30_registry/assets/extra.css** — CSS-стили
7. **docs/30_registry/javascripts/fix-slash.js** — JS (trailing slash fix)
### Посмотреть живьём (если есть доступ):
- https://tf-registry.containerk8s.services.ngcloud.ru/docs/nubes-test/nubes/5.0.5/ — индекс ресурсов
- https://tf-registry.containerk8s.services.ngcloud.ru/docs/nubes-test/nubes/5.0.5/postgres_params_create/ — пример страницы параметров PostgreSQL
- https://tf-registry.containerk8s.services.ngcloud.ru/docs/nubes-test/nubes/5.0.5/postgres_example/ — пример HCL
---
## 8. ОГРАНИЧЕНИЯ
- **YAML = истина.** Параметры, типы, defaults, constraints берутся ТОЛЬКО из YAML. Не выдумывать.
- **mkdocs-material** — выбранный фреймворк. Менять можно в рамках его возможностей.
- **43 сервиса** — масштаб. Решения должны работать для всех, не только для PostgreSQL.
- **Русский язык** — вся документация на русском.
- **Целевая аудитория** — DevOps-инженеры, знают Terraform, не знают внутренностей Nubes.
---
## 9. ФОРМАТ ОТВЕТА
Жду от тебя **структурированный анализ**:
1. **Общая оценка** текущего состояния документации (что хорошо, что плохо)
2. **Детальные рекомендации** по каждому блоку вопросов (A1-E2)
3. **Приоритизированный план действий** (Quick wins → Среднесрок → Долгосрок)
4. **Конкретные предложения** по коду/CSS/структуре где применимо
5. **Антипаттерны** — что НЕ стоит делать и почему
Не спеши. Изучи все файлы. Подумай как ДЕВОПС который впервые видит этот провайдер и пытается написать манифест для PostgreSQL.
---
## 10. УТОЧНЯЮЩИЙ ВОПРОС: Как смержить nav
Ты рекомендуешь вернуть sidebar с категориями. Но в `mkdocs.yml` секция `nav:` — статическая (руководства, глоссарий), а ресурсы генерируются динамически через `WriteNavFragment()` в `_nav_fragment.yml`.
Как правильно смержить статический `nav:` (руководства) и динамический (43 ресурса по категориям) в mkdocs?
---
### Ответ Соннета
**Нет встроенного `!include` в mkdocs.** mkdocs-material не имеет нативного механизма подключения внешних YAML-фрагментов в `nav:`.
**Вариант 1 — Рекомендован: расширить существующий Python pre-build шаг**
В `04_build_and_publish_docs.sh` уже есть Python-блок, который пишет `.mkdocs.tmp.yml`. Добавить туда чтение `_nav_fragment.yml` и инъекцию в `nav:`:
```python
import yaml
nav_fragment_path = Path(docs_dir) / "_nav_fragment.yml"
if nav_fragment_path.exists():
fragment = yaml.safe_load(nav_fragment_path.read_text(encoding="utf-8"))
resources_nav = fragment.get("resources_nav", [])
config = yaml.safe_load(text)
for item in config.get("nav", []):
if isinstance(item, dict) and "Ресурсы" in item:
item["Ресурсы"] = resources_nav
break
text = yaml.dump(config, allow_unicode=True, default_flow_style=False, sort_keys=False)
```
Плюсы: ноль новых зависимостей, PyYAML уже в окружении, merge в одном месте.
**Вариант 2:** docs-generator пишет полный mkdocs.yml (сложнее поддерживать).
**Вариант 3:** mkdocs-awesome-pages (не решает проблему merge).
**Дополнительно:** когда `docs_dir` переключается на `generated/{stand}/docs_llm`, пути `30_registry/guides/*.md` ломаются. Решение: копировать `30_registry` в `docs_dir` перед сборкой.
**Итого:** Вариант 1 — минимальные изменения, всё уже на месте.