From 04d9c4a191e3d08da2681927394b06c25f8c2539 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E2=80=9CNaeel=E2=80=9D?= Date: Mon, 10 Aug 2026 13:48:25 +0400 Subject: [PATCH] feat(Phase 2): unified params table (Required col), MAN in details, danger admonition for lifecycle --- .../internal/writers/writers.go | 75 ++++++++++++------- TOOLS/scripts/05_generate_docs_llm.py | 19 ++++- 2 files changed, 61 insertions(+), 33 deletions(-) diff --git a/TOOLS/docs-generator/internal/writers/writers.go b/TOOLS/docs-generator/internal/writers/writers.go index 6a6421a..02596fe 100644 --- a/TOOLS/docs-generator/internal/writers/writers.go +++ b/TOOLS/docs-generator/internal/writers/writers.go @@ -151,14 +151,23 @@ func buildHeader(spec types.ServiceSpec, nav string, version string) string { func buildManualPage(spec types.ServiceSpec, nav string, version string) string { var b strings.Builder b.WriteString(buildHeader(spec, nav, version)) - b.WriteString("## MAN\n\n") - man := strings.TrimSpace(spec.ServiceMan) - if man == "" { - man = "Manual not available." + + // Краткое описание + name := spec.ServiceDisplayName + if name == "" { + name = spec.Name + } + b.WriteString(fmt.Sprintf("Сервис **%s** (`nubes_%s`). См. [Create params](%s_params_create.md) для списка параметров.\n\n", name, spec.Name, spec.Name)) + + // MAN в раскрывающемся блоке — DevOps читает если застрял + man := strings.TrimSpace(spec.ServiceMan) + if man != "" { + b.WriteString("
\nСправка (MAN)\n\n") + b.WriteString("
\n\n") + b.WriteString(htmlToMarkdown(man)) + b.WriteString("\n\n
\n") + b.WriteString("
\n") } - b.WriteString("
\n\n") - b.WriteString(htmlToMarkdown(man)) - b.WriteString("\n\n
\n") return b.String() } @@ -303,37 +312,45 @@ func buildCreateParamsPage(spec types.ServiceSpec, nav string, version string) s b.WriteString(buildHeader(spec, nav, version)) b.WriteString("## Create params\n\n") createParams := FindParams(spec.Operations, "create") - requiredParams, defaultParams := SplitParams(createParams) - if len(requiredParams) > 0 { - b.WriteString("**Обязательные параметры (вводимые пользователем)**\n\n") - b.WriteString(renderParamTable(requiredParams, true, true)) - for _, p := range requiredParams { - b.WriteString(renderNestedParams(p)) + if len(createParams) > 0 { + b.WriteString("| Параметр | Тип | Обязательный | По умолчанию | Описание | Ограничения |\n") + b.WriteString("|----------|-----|-------------|-------------|----------|-------------|\n") + for _, p := range createParams { + code := formatParamCode(p.Code) + dtype := formatTypeCell(p) + req := "—" + if p.Required { + req = "**да**" + } + def := defaultCell(p.Default) + desc := escapeText(pickTextTable(p)) + constr := escapeText(collectConstraints(p)) + b.WriteString(fmt.Sprintf("| %s | %s | %s | %s | %s | %s |\n", code, dtype, req, def, desc, constr)) } - } + b.WriteString("\n") - if len(defaultParams) > 0 { - b.WriteString("\n**Параметры, имеющие значение по умолчанию, если не меняете - эти параметры не обязательно прописывать в манифесте**\n") - b.WriteString(renderParamTable(defaultParams, false, false)) - for _, p := range defaultParams { + // Вложенные параметры (map-fixed) + for _, p := range createParams { b.WriteString(renderNestedParams(p)) } } lifecycle := spec.Lifecycle if lifecycle.SuspendOnDestroyDefault || lifecycle.AdoptExistingOnCreateDefault { - b.WriteString("\n
\n") - b.WriteString("Параметры поведения (кратко)
\n") - b.WriteString(fmt.Sprintf("По умолчанию: `suspend_on_destroy = %s`, `adopt_existing_on_create = %s`.
\n", formatBoolTitle(lifecycle.SuspendOnDestroyDefault), formatBoolTitle(lifecycle.AdoptExistingOnCreateDefault))) - b.WriteString("При `terraform destroy` или удалении ресурса из манифеста:
\n") - b.WriteString("- `suspend_on_destroy=true` — инстанс переводится в `Suspend` (не удаляется).
\n") - b.WriteString("- `suspend_on_destroy=false` — Terraform удаляет ресурс только из state.
\n") - b.WriteString("При `apply` флаг `adopt_existing_on_create` работает как авто-`import`:
\n") - b.WriteString("- `false` — если ресурс уже есть, будет ошибка.
\n") - b.WriteString("- `true` — Terraform может взять существующий инстанс под управление (`running` → adopt, `suspended` → resume+adopt при совпадении параметров).
\n") - b.WriteString("Важно: один инстанс должен быть только в одном state. Иначе получите конфликт управления.\n") - b.WriteString("
\n") + b.WriteString("\n!!! danger \"Важно: поведение при destroy\"\n") + b.WriteString(fmt.Sprintf(" По умолчанию: `suspend_on_destroy = %s`, `adopt_existing_on_create = %s`.\n", formatBoolTitle(lifecycle.SuspendOnDestroyDefault), formatBoolTitle(lifecycle.AdoptExistingOnCreateDefault))) + b.WriteString(" \n") + b.WriteString(" При `terraform destroy` или удалении ресурса из манифеста:\n") + b.WriteString(" - `suspend_on_destroy=true` — инстанс переводится в `Suspend` (не удаляется).\n") + b.WriteString(" - `suspend_on_destroy=false` — Terraform удаляет ресурс только из state.\n") + b.WriteString(" \n") + b.WriteString(" При `apply` флаг `adopt_existing_on_create` работает как авто-`import`:\n") + b.WriteString(" - `false` — если ресурс уже есть, будет ошибка.\n") + b.WriteString(" - `true` — Terraform может взять существующий инстанс под управление.\n") + b.WriteString(" \n") + b.WriteString(" Важно: один инстанс должен быть только в одном state. Иначе получите конфликт управления.\n") + b.WriteString("\n") } return b.String() diff --git a/TOOLS/scripts/05_generate_docs_llm.py b/TOOLS/scripts/05_generate_docs_llm.py index 4b9eaef..a4523c1 100644 --- a/TOOLS/scripts/05_generate_docs_llm.py +++ b/TOOLS/scripts/05_generate_docs_llm.py @@ -25,14 +25,24 @@ SYSTEM_PROMPT = """Ты — технический писатель Nubes Terraf - НЕ трогай HCL-блоки (всё внутри ```hcl ... ```) - НЕ трогай имена параметров в таблицах (snake_case / camelCase из API) - НЕ трогай навигационные строки вида [Manual](x.md) · [Create params](y.md) ... +- НЕ трогай блоки `!!! danger` — это автоматические предупреждения - НЕ добавляй и не удаляй строки/колонки в таблицах - Верни ТОЛЬКО готовый текст файла. Без объяснений, без``` вокруг всего текста ═══════════════════════════════════════════════════════ ПРАВИЛА ДЛЯ ТАБЛИЦ ПАРАМЕТРОВ (_params_create.md, _params_modify.md) ═══════════════════════════════════════════════════════ -Таблицы содержат столбцы: ID | Code | Type | Required | Default | Description | Constraints -Можно менять ТОЛЬКО текст в Description и Constraints. +Таблицы create-параметров содержат столбцы: + Параметр | Тип | Обязательный | По умолчанию | Описание | Ограничения + +Таблицы modify-параметров содержат столбцы: + Code | Type | Description | Constraints + +Таблицы вложенных параметров (### map-fixed) содержат столбцы: + Code | Type | Required | Default | Description | Constraints + +Можно менять ТОЛЬКО текст в колонках Описание/Description и Ограничения/Constraints. +НЕ трогай колонки: Параметр/Code, Тип/Type, Обязательный/Required, По умолчанию/Default. ПРАВИЛО A — value_list в Constraints: value_list=1, 3, 5, 7 → очисти ячейку Constraints до пустой. @@ -76,9 +86,10 @@ SYSTEM_PROMPT = """Ты — технический писатель Nubes Terraf recovery → «Восстановление из резервной копии» ═══════════════════════════════════════════════════════ -ПРАВИЛА ДЛЯ ГЛАВНОЙ СТРАНИЦЫ (Name.md — секция ## MAN) +ПРАВИЛА ДЛЯ ГЛАВНОЙ СТРАНИЦЫ (Name.md — блок
) ═══════════════════════════════════════════════════════ -Блок ## MAN содержит HTML внутри
. +MAN находится внутри `
Справка (MAN)` — НЕ трогай теги details/summary. +Внутри — HTML в `
`. Преобразуй HTML → читаемый Markdown:

/

→ ## / ###
  • → - элемент списка