From 21b92f46319163c77c8b6052175bd03a33c5ac75 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E2=80=9CNaeel=E2=80=9D?= Date: Mon, 10 Aug 2026 13:32:09 +0400 Subject: [PATCH] =?UTF-8?q?docs:=20Q&A=20with=20Sonnet=20=E2=80=94=20UX=20?= =?UTF-8?q?analysis=20+=20nav=20merge=20strategy=20(Phase=201-3=20plan)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- HISTORY/SONNET/2026-08-10_docs_ux_analysis.md | 183 +++++++++ HISTORY/SONNET/2026-08-10_nav_merge_answer.md | 61 +++ docs/LLM_DOCS_GENERATION.md | 13 + prompt_for_sonnet_docs_ux.md | 359 ++++++++++++++++++ 4 files changed, 616 insertions(+) create mode 100644 HISTORY/SONNET/2026-08-10_docs_ux_analysis.md create mode 100644 HISTORY/SONNET/2026-08-10_nav_merge_answer.md create mode 100644 prompt_for_sonnet_docs_ux.md diff --git a/HISTORY/SONNET/2026-08-10_docs_ux_analysis.md b/HISTORY/SONNET/2026-08-10_docs_ux_analysis.md new file mode 100644 index 0000000..5c42a56 --- /dev/null +++ b/HISTORY/SONNET/2026-08-10_docs_ux_analysis.md @@ -0,0 +1,183 @@ +# Ответ Соннета: Анализ UX документации Nubes Terraform Provider + +**Дата:** 2026-08-10 +**Вопрос:** см. prompt_for_sonnet_docs_ux.md +**Ответчик:** Claude Sonnet + +--- + +## TL;DR + +Документация функционально корректна, но навигация сломана для нового пользователя — он не может найти нужный ресурс без знания URL. Три приоритета: восстановить sidebar, сделать главную страницу рабочей, поднять размер шрифта MAN. + +--- + +## 1. Общая оценка + +**Хорошо:** +- YAML → Markdown пайплайн — надёжная основа, параметры актуальны +- Cloud snapshot для `state_out_flat` / `vault_secrets` — уникальная ценность, ни у кого нет +- Dual example (minimal + full) — правильный выбор + +**Плохо:** +- Боковые панели скрыты → юзер попадает на страницу и не знает как вернуться к другим ресурсам +- `font-size: 0.62rem` для MAN — нечитаемо, создаёт впечатление "broken UI" +- Версия в URL, но не в UI → юзер не уверен смотрит ли он актуальное +- Индексная страница — голая таблица из 43 строк без группировки и фильтрации + +--- + +## 2. Рекомендации по блокам + +### A. Навигация + +**A1 — Навигация между ресурсами:** +Лучший вариант — вернуть левый sidebar с категориями. 43 ресурса легко разбиваются на группы: +- **Базы данных**: postgres, mysql, redis, mongodb, ... +- **Очереди**: kafka, rabbitmq, activemq, ... +- **Хранилище**: s3, swift, ... +- **K8s**: kubernetes, helm, ... +- **VMware**: vdc, vm, ... +- **Приложения**: lucee, nodejs, flask, ... +- **Сеть/прочее**: остальное + +Sidebar с категориями даёт ориентацию за 3 секунды. Поиск mkdocs (`search`) — бесплатный бонус. + +**A2 — Вернуть sidebar:** +Да. Убрать из `extra.css` строки: +```css +.md-sidebar--primary { display: none !important; } +``` +Правый sidebar (TOC) убрать только для страниц ресурсов — там он бесполезен. Реализуется через meta-tag `hide: [toc]` в frontmatter генерируемых файлов. + +**A3 — Быстрый поиск:** +- Включить встроенный поиск mkdocs-material (`search` plugin) +- В `IndexMD()` добавить категории как `## Базы данных`, `## Очереди` — тогда sidebar mkdocs покажет дерево + +--- + +### B. Дизайн страницы ресурса + +**B1 — MAN font-size:** +Поднять с `0.62rem` до `0.78rem` — достаточно компактно, но читаемо. Заодно обернуть MAN в `
` с заголовком "Справка (MAN)" — DevOps обычно не читает MAN, ему нужны параметры. + +**B2 — Структура страницы:** +Текущий порядок (MAN в начале) — неоптимален. Предлагаю: +``` +1. Заголовок + Inline nav +2. Краткое описание (1-2 строки из ServiceDisplayName + первый абзац MAN) +3. Minimal example (СРАЗУ — копируй и пробуй) +4. Create params (таблица) +5. Outputs (state_out_flat + vault_secrets) +6. MAN (в
collapsed) +``` +DevOps хочет пример → понял структуру → посмотрел параметры. MAN читает если застрял. + +Это изменение в `buildManualPage()` — перенос `buildExamplePage()` фрагмента вверх. Либо создать новый `buildCombinedLandingPage()`. + +**B3 — Версия в UI:** +Добавить в `buildHeader()`: +``` +# Resource nubes_postgres · v5.0.5 · Service ID: 90 · PostgreSQL +``` +`version` уже передаётся в `ResourceDocs()` — просто прокинуть в `buildHeader()`. + +--- + +### C. Таблицы параметров + +**C1 — Колонки таблиц:** +Текущие колонки: `Code | Type | Description | Constraints`. Добавить `Required` и `Default`: +``` +| Параметр | Тип | Обязательный | По умолчанию | Описание | Ограничения | +``` +`Required` и `Default` уже есть в данных (`SplitParams()` их разделяет), просто не выводятся в единой таблице. Убрать разделение на две таблицы — одна таблица с колонкой Required проще для чтения. + +**C2 — Вложенные параметры (map-fixed):** +Текущий вариант (`### clusterConfiguration` → отдельная таблица) — приемлем. Улучшить: добавить ссылку-якорь в основной таблице: +``` +| clusterConfiguration | map-fixed | [Развернуть ↓](#clusterconfiguration) | ... | +``` +Так юзер понимает что кликнуть. Реализуется в `renderParamTable()` + `renderNestedParams()`. + +--- + +### D. Примеры + +**D1 — Страница Example:** +- Поменять местами: Minimal example → Full example (не в `
`) + Сейчас Full в раскрывашке — правильно. Но заголовок `Minimal example — only required parameters` на английском среди русского контента — резает глаз. Перевести. +- Добавить комментарии в код: `# Выберите из: 1, 3, 5` для параметров с value_list — LLM уже обогащает, но это должно быть в HCL-примере тоже. +- Outputs usage: сейчас шаблонные строки с `baza`. Показать реальные ключи из cloud snapshot если есть: + ```hcl + # PostgreSQL connection string: + # nubes_postgres.baza.state_out_flat["internalConnect.master"] + ``` + +--- + +### E. Общие рекомендации + +**E1 — Чего не хватает:** +1. **Lifecycle warning** — блок про `suspend_on_destroy` сейчас внизу create params мелким шрифтом. Это КРИТИЧНАЯ информация (пользователь может случайно "удалить" БД). Поднять выше, оформить как `!!! danger` admonition. +2. **Связанные ресурсы** — PostgreSQL → пример связки с Lucee/NodeJS уже есть в `buildOutputsPage()`, но только для service_id=90. Обобщить через теги в YAML. +3. **Changelog** — нужен, но это отдельная задача (нужно хранить diff между версиями YAML). + +**E2 — Приоритеты:** +Quick wins (высокий эффект, минимум кода): +1. Убрать `display:none` с primary sidebar + включить search +2. MAN font-size 0.62rem → 0.78rem +3. Версия в buildHeader() +4. Добавить категории в IndexMD() + _nav_fragment.yml + +--- + +## 3. Приоритизированный план действий + +**Phase 1 — Quick wins (1-2 дня, 1 разработчик)** +1. `extra.css`: убрать `display:none` для primary sidebar +2. `extra.css`: MAN font-size `0.62rem` → `0.78rem` +3. writers.go: прокинуть `version` в `buildHeader()` +4. `IndexMD()`: добавить категорийные заголовки (требует маппинга service → category) +5. `WriteNavFragment()`: группировка по категориям в `_nav_fragment.yml` + +**Phase 2 — Структура страницы (3-5 дней)** +6. Новый порядок секций: пример → параметры → MAN в `
` +7. Объединить required/defaults в одну таблицу с колонкой Required +8. Lifecycle warning → admonition `danger` + +**Phase 3 — Таблицы и примеры (1 неделя)** +9. Якори для вложенных параметров +10. Реальные ключи из cloud snapshot в HCL-примерах +11. Перевести заголовки примеров на русский + +**Долгосрок (отдельный эпик)** +12. Changelog между версиями +13. Теги для связанных ресурсов + +--- + +## 4. Конкретные предложения по коду + +| Файл | Изменение | +|------|-----------| +| extra.css | Убрать строки `display: none !important` для обоих sidebar; MAN `.man-content` `font-size: 0.78rem` | +| `writers/writers.go`: `buildHeader()` | Добавить `version` параметр, вывести в заголовок | +| `writers/writers.go`: `IndexMD()` | Принять маппинг `categoryMap map[int]string`, выводить заголовки `## Category` | +| `writers/writers.go`: `buildCreateParamsPage()` | Единая таблица Required + Default с колонкой Required (bool); lifecycle → admonition | +| `writers/writers.go`: `buildManualPage()` | MAN обернуть в `
Справка (MAN)` | +| mkdocs.yml | Включить `search` plugin | + +--- + +## 5. Антипаттерны — что НЕ делать + +1. **Не делать многоуровневую sidebar по операциям** — `Manual / Create params / Modify params` в sidebar превратит дерево в 43×6=258 пунктов. Только верхний уровень в sidebar, внутри — inline nav. +2. **Не трогать LLM prompt ради структуры** — структура страниц это Go-генератор, не LLM. LLM только обогащает тексты. +3. **Не делать HTML-таблицы** — Markdown-таблицы уже работают; HTML нужен только для сложных случаев (`lifecycle-note` div — допустимо). +4. **Не скрывать пример в `
`** — сейчас Full example скрыт, это правильно. Minimal должен быть ОТКРЫТ и первым. +5. **Не добавлять JS-фильтрацию на index** — mkdocs search уже умеет фильтровать; второй поиск создаёт путаницу. + +--- + +**Ключевой вывод:** Самое больное место — отсутствие sidebar и нечитаемый MAN. Эти два изменения (по 3 строки CSS) дадут 80% UX-эффекта. Остальное — итеративно. diff --git a/HISTORY/SONNET/2026-08-10_nav_merge_answer.md b/HISTORY/SONNET/2026-08-10_nav_merge_answer.md new file mode 100644 index 0000000..22f4f31 --- /dev/null +++ b/HISTORY/SONNET/2026-08-10_nav_merge_answer.md @@ -0,0 +1,61 @@ +# Ответ Соннета: Как смержить nav (статический + динамический) + +**Дата:** 2026-08-10 +**Вопрос:** Как смержить статический `nav:` (руководства) и динамический (43 ресурса по категориям) в mkdocs? +**Ответчик:** Claude Sonnet + +--- + +## Нет встроенного `!include` в mkdocs + +mkdocs-material не имеет нативного механизма подключения внешних YAML-фрагментов в `nav:`. Плагины (monorepo, awesome-pages) решают другие задачи и здесь не помогут. + +--- + +## Три варианта (по убыванию рекомендованности) + +### Вариант 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 docs_dir else None +if nav_fragment_path and 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 в одном месте, статические секции ("Руководства") остаются нетронутыми. + +**Предупреждение:** PyYAML при `dump` меняет форматирование (кавычки, отступы) — это нормально для `.mkdocs.tmp.yml`, который никто не читает руками. + +### Вариант 2: docs-generator пишет полный mkdocs.yml + +Сделать отдельный файл `mkdocs_base.yml` (тема, плагины, CSS, статический nav — без ресурсов), Go-генератор его читает, добавляет ресурсный nav, пишет финальный mkdocs.yml. + +**Минус:** Go-генератор становится ответственным за весь mkdocs.yml, сложнее поддерживать структуру темы/плагинов. + +### Вариант 3: mkdocs-awesome-pages + +Плагин создаёт `.pages` файлы в директориях и управляет порядком через них. Но `nav:` в mkdocs.yml при этом должен быть либо полностью убран, либо включать ресурсы явно — проблему merge не решает. + +--- + +## Дополнительная проблема: guides при смене `docs_dir` + +Когда `docs_dir` переключается на `generated/{stand}/docs_llm`, пути вида `30_registry/guides/getting-started.md` в `nav:` ломаются — этих файлов там нет. + +**Решение:** в том же Python pre-build шаге скопировать `30_registry` в `$MKDOCS_DOCS_DIR/30_registry/` перед сборкой. Или — убрать guides из профильного nav (оставить только ресурсы). + +--- + +**Итого:** Вариант 1 — минимальные изменения, всё уже на месте. Нужно только расширить существующий Python блок в `04_build_and_publish_docs.sh` примерно на 10 строк + скопировать `30_registry` в `docs_dir`. diff --git a/docs/LLM_DOCS_GENERATION.md b/docs/LLM_DOCS_GENERATION.md index 89816f3..f7ad9e2 100644 --- a/docs/LLM_DOCS_GENERATION.md +++ b/docs/LLM_DOCS_GENERATION.md @@ -98,3 +98,16 @@ MAN: 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) diff --git a/prompt_for_sonnet_docs_ux.md b/prompt_for_sonnet_docs_ux.md new file mode 100644 index 0000000..3cd71b0 --- /dev/null +++ b/prompt_for_sonnet_docs_ux.md @@ -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) в раскрывашке `
` +- Юзер может скопировать и использовать + +### 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 в `
` +- Добавить: описание каждого блока? комментарии в коде? +- Показывать реальные значения из облака? + +### Блок 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 — минимальные изменения, всё уже на месте.