feat(Phase 2): unified params table (Required col), MAN in details, danger admonition for lifecycle
This commit is contained in:
“Naeel”
@@ -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("<details>\n<summary>Справка (MAN)</summary>\n\n")
|
||||
b.WriteString("<div class=\"man-content\" markdown=\"1\">\n\n")
|
||||
b.WriteString(htmlToMarkdown(man))
|
||||
b.WriteString("\n\n</div>\n")
|
||||
b.WriteString("</details>\n")
|
||||
}
|
||||
b.WriteString("<div class=\"man-content\" markdown=\"1\">\n\n")
|
||||
b.WriteString(htmlToMarkdown(man))
|
||||
b.WriteString("\n\n</div>\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<div class=\"lifecycle-note\">\n")
|
||||
b.WriteString("<strong>Параметры поведения (кратко)</strong><br/>\n")
|
||||
b.WriteString(fmt.Sprintf("По умолчанию: `suspend_on_destroy = %s`, `adopt_existing_on_create = %s`.<br/>\n", formatBoolTitle(lifecycle.SuspendOnDestroyDefault), formatBoolTitle(lifecycle.AdoptExistingOnCreateDefault)))
|
||||
b.WriteString("При `terraform destroy` или удалении ресурса из манифеста:<br/>\n")
|
||||
b.WriteString("- `suspend_on_destroy=true` — инстанс переводится в `Suspend` (не удаляется).<br/>\n")
|
||||
b.WriteString("- `suspend_on_destroy=false` — Terraform удаляет ресурс только из state.<br/>\n")
|
||||
b.WriteString("При `apply` флаг `adopt_existing_on_create` работает как авто-`import`:<br/>\n")
|
||||
b.WriteString("- `false` — если ресурс уже есть, будет ошибка.<br/>\n")
|
||||
b.WriteString("- `true` — Terraform может взять существующий инстанс под управление (`running` → adopt, `suspended` → resume+adopt при совпадении параметров).<br/>\n")
|
||||
b.WriteString("Важно: один инстанс должен быть только в одном state. Иначе получите конфликт управления.\n")
|
||||
b.WriteString("</div>\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()
|
||||
|
||||
@@ -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
|
||||
Можно менять ТОЛЬКО текст в <td>Description</td> и <td>Constraints</td>.
|
||||
Таблицы 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 — блок <details>)
|
||||
═══════════════════════════════════════════════════════
|
||||
Блок ## MAN содержит HTML внутри <div class="man-content">.
|
||||
MAN находится внутри `<details><summary>Справка (MAN)</summary>` — НЕ трогай теги details/summary.
|
||||
Внутри — HTML в `<div class="man-content" markdown="1">`.
|
||||
Преобразуй HTML → читаемый Markdown:
|
||||
<h2>/<h3> → ## / ###
|
||||
<ul><li> → - элемент списка
|
||||
|
||||
Reference in New Issue
Block a user