docs: Q&A with Sonnet — UX analysis + nav merge strategy (Phase 1-3 plan)
This commit is contained in:
“Naeel”
@@ -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 в `<details>` с заголовком "Справка (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 (в <details> 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 (не в `<details>`)
|
||||
Сейчас 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 в `<details>`
|
||||
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 обернуть в `<details><summary>Справка (MAN)</summary>` |
|
||||
| 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. **Не скрывать пример в `<details>`** — сейчас Full example скрыт, это правильно. Minimal должен быть ОТКРЫТ и первым.
|
||||
5. **Не добавлять JS-фильтрацию на index** — mkdocs search уже умеет фильтровать; второй поиск создаёт путаницу.
|
||||
|
||||
---
|
||||
|
||||
**Ключевой вывод:** Самое больное место — отсутствие sidebar и нечитаемый MAN. Эти два изменения (по 3 строки CSS) дадут 80% UX-эффекта. Остальное — итеративно.
|
||||
@@ -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`.
|
||||
@@ -98,3 +98,16 @@ MAN: <service_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)
|
||||
|
||||
@@ -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 — минимальные изменения, всё уже на месте.
|
||||
Reference in New Issue
Block a user