terraform/tf_provider

Fork 0

Files

T

“Naeel” dc5bac376c docs: MAN format fix history + instructions (??? admonition, not details/div)

2026-08-10 17:16:54 +04:00

9.4 KiB

Raw Permalink Blame History

Архитектура документации 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()`

// 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 (&quot; → ")
// 10. Collapse 3+ blank lines → 2

Рендеринг: `??? note` admonition (НЕ `<details>`!)

Важно: <details> и <div markdown="1"> НЕ работают в mkdocs — Markdown внутри них не рендерится.

Вместо этого используется нативный mkdocs admonition ??? note:

??? note "Справка (MAN)"

    # Инструкция по развертыванию
    
    ---
    ## 1. Общая информация
    Текст параграфа.
    
    - **bold** — описание
    - `code` — пример

Критические требования:

Пустая строка после ??? note "..." — обязательно
Все строки контента с отступом ровно 4 пробела — включая пустые
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 ===
<содержимое>
...

Формат выхода

{
  "Name.md": "полный текст",
  "Name_example.md": "полный текст",
  ...
}

Правила для LLM

YAML = истина. MAN = контекст. Если противоречат → верить YAML.
HTML-таблицы: менять ТОЛЬКО текст внутри <td>, НЕ трогать структуру тегов.
HCL-блоки: НЕ трогать.
Navigation-строки: НЕ трогать.
Имена ресурсов (nubes_*): НЕ менять.
MAN-секцию: перевести из HTML в читаемый Markdown.
Описания: сделать грамотными, логичными, на русском. Добавить контекст из MAN где уместно.
Юзер в первую очередь смотрит на: имя переменной, required/default, что делает параметр. Это должно быть максимально понятно.

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

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

WriteNavFragment() генерирует _nav_fragment.yml с resources_nav: (категории + ресурсы)
Python-блок читает _nav_fragment.yml, парсит mkdocs.yml, вставляет ресурсы в секцию Ресурсы внутри nav:
Одновременно копирует 30_registry/ в docs_dir (чтобы guides не ломались при смене docs_dir)
Результат пишется в .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-спеках, не влияют на корректность.

9.4 KiB Raw Permalink Blame History Unescape Escape