docs: пометить отменённый заход модификаторов как LEGACY + исправить ложные факты
- баннеры «ЛОЖНЫЙ ПУТЬ — ОТМЕНЕНО» на 4 файла HISTORY/OPUS/2026-09-22_modifier_* и docs/60_strategy/modifier_resources_ideology_and_specification.md - vIPConfigure: replace-семантика, НЕ накопительная (по тесту docs/ORG_IP_MODIFIER_TEST_2026-09-22.md) - обновлены ссылки на перенесённые материалы (docs/... -> NOTES/..., HOW_TO/...)
This commit is contained in:
Repinoid
@@ -0,0 +1,182 @@
|
||||
# Архитектура документации 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 в `??? note` (mkdocs-native admonition) |
|
||||
| `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 |
|
||||
|
||||
## Формат MAN (service_man) — как рендерится
|
||||
|
||||
`service_man` из YAML содержит **смесь Markdown и HTML**: заголовки `#`/`##`, списки `-`, bold `**`, горизонтальные линии `---`, а также `<br/>` и HTML-entities.
|
||||
|
||||
### Конвертация: `htmlToMarkdown()`
|
||||
|
||||
```go
|
||||
// 1. <br/> → \n
|
||||
// 2. <h1>/<h2>/<h3> → # / ## / ###
|
||||
// 3. <strong>/<b> → **...**
|
||||
// 4. <em>/<i> → *...*
|
||||
// 5. <code> → `...`
|
||||
// 6. <a href> → [...](...)
|
||||
// 7. <ul><li> → - ...
|
||||
// 8. Strip remaining HTML tags
|
||||
// 9. Unescape HTML entities (" → ")
|
||||
// 10. Collapse 3+ blank lines → 2
|
||||
```
|
||||
|
||||
### Рендеринг: `??? note` admonition (НЕ `<details>`!)
|
||||
|
||||
**Важно:** `<details>` и `<div markdown="1">` НЕ работают в mkdocs — Markdown внутри них не рендерится.
|
||||
|
||||
Вместо этого используется **нативный mkdocs admonition** `??? note`:
|
||||
|
||||
```markdown
|
||||
??? note "Справка (MAN)"
|
||||
|
||||
# Инструкция по развертыванию
|
||||
|
||||
---
|
||||
## 1. Общая информация
|
||||
Текст параграфа.
|
||||
|
||||
- **bold** — описание
|
||||
- `code` — пример
|
||||
```
|
||||
|
||||
**Критические требования:**
|
||||
1. Пустая строка после `??? note "..."` — обязательно
|
||||
2. Все строки контента с отступом ровно 4 пробела — включая пустые
|
||||
3. `pymdownx.details` в `markdown_extensions` (уже есть)
|
||||
|
||||
Результат: `<details class="note"><summary>Справка (MAN)</summary><h1>...</h1><hr/><h2>...</h2>...</details>`
|
||||
|
||||
## Принципы дизайна (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)
|
||||
|
||||
## Аудит соответствия YAML ↔ Доки (2026-08-10)
|
||||
|
||||
**Метод:** сравнение всех 37 YAML-спеков со сгенерированными `_params_create.md` и `_params_modify.md`.
|
||||
|
||||
### Итоги
|
||||
|
||||
| Метрика | YAML | Доки | Статус |
|
||||
|---------|------|------|--------|
|
||||
| Сервисов | 37 | 37 | ✅ |
|
||||
| CREATE params (top-level) | 204 | 204 | ✅ 1:1 |
|
||||
| MODIFY params (top-level) | 102 | 101 | ⚠️ -1 |
|
||||
| Sub-params (nested) | — | 199 | ✅ развёрнуты |
|
||||
|
||||
### Расхождения
|
||||
|
||||
| # | Сервис | Проблема | Причина | Действие |
|
||||
|---|--------|----------|---------|----------|
|
||||
| 1 | vc_vm_v2 | Нет страниц | Закомментирован в `services_list.txt` (`# нет в TEST UI`) | Не баг |
|
||||
| 2 | s3, s3bucket, dummy, vc_nsxt, vcexternalip, vc_vm_v3 | 8 пустых типов | Поле `type` не заполнено в YAML | Косметика |
|
||||
|
||||
### Вывод
|
||||
|
||||
Все параметры из YAML **полностью** присутствуют в документации. CamelCase-имена корректно конвертируются в snake_case через `ToSnake()`. Единственный «missing» сервис (vc_vm_v2) исключён из генерации намеренно. 8 пустых типов — пробелы в исходных YAML-спеках, не влияют на корректность.
|
||||
Reference in New Issue
Block a user