feat: новый дизайн документации — шаблон, генератор, CSS, md_in_html, версия 5.1.2

2026-07-18 09:50:37 +03:00
parent 1276143973
commit ad3b986d89
6 changed files with 253 additions and 79 deletions
@@ -0,0 +1,35 @@
+# План редизайна таблиц документации (Этап 1 — CSS)
+
+> На основе рекомендаций Соннета. Только CSS, без правок генератора.
+
+## Что делаем
+
+| # | Изменение | CSS |
+|---|---|---|
+| 1 | Убрать ID | `display: none` на `th:nth-child(1)`, `td:nth-child(1)` |
+| 2 | ★ вместо колонки Required | Скрыть `td:nth-child(4)` в nested, `::before` на Code для required строк |
+| 3 | Monospace для Constraints | `font-family: monospace`, `overflow-wrap: anywhere` |
+| 4 | Sticky thead | `position: sticky; top: 0` |
+| 5 | line-clamp(2) Description | `-webkit-line-clamp: 2`, `overflow: hidden` |
+| 6 | Zebra striping | `tr:nth-child(even) { background: #fafafa }` |
+| 7 | Новые ширины колонок | Пересчёт после удаления ID и Required |
+
+## Новые ширины
+
+**Основная таблица (4 колонки, без ID):**
+Code(22%) | Type(6%) | Description(42%) | Constraints(30%)
+
+**Основная с Default (5 колонок):**
+Code(22%) | Type(5%) | Default(10%) | Description(33%) | Constraints(30%)
+
+**Nested (5 колонок, без ID и Required):**
+★Code(22%) | Type(5%) | Default(10%) | Description(33%) | Constraints(30%)
+
+## Порядок действий
+
+1. Обновить `extra.css`
+2. Скопировать в `generated/test/docs/30_registry/assets/`
+3. Пересобрать `site_test` через Docker
+4. Перезапустить HTTP-сервер
+5. Проверить в браузере
+6. Закоммитить через ВМ
@@ -0,0 +1,96 @@
+# Шаблон страницы ресурса (документация)
+
+> Актуально на 2026-07-18. Применять ко всем сервисам.
+
+## Структура страницы
+
+```markdown
+# Resource nubes_SERVICE · Service ID: N · Service Name: DISPLAY_NAME
+
+**Manual** · [Create params](SERVICE_params_create.md) · [Modify params](SERVICE_params_modify.md) · [Output params](SERVICE_outputs.md) · [Operations](SERVICE_ops.md) · [Example](SERVICE_example.md)
+```
+
+**Правила:**
+- Заголовок — ОДНА строка, разделители `·`
+- Табы — активная вкладка `**жирным**`, разделители `·`
+- SERVICE = имя ресурса из YAML (`spec.Name`), DISPLAY_NAME = `spec.ServiceDisplayName`
+
+## MAN
+
+```markdown
+## MAN
+
+<div class="man-content" markdown="1">
+
+# Инструкция ...
+
+...
+
+</div>
+```
+
+- Весь MAN-контент внутри `<div class="man-content" markdown="1">`
+- Шрифт: 0.62rem (CSS: `.md-typeset .man-content`)
+- Требует `md_in_html` в `mkdocs.yml`
+
+## Таблицы параметров
+
+### Основная (Create/Modify params)
+
+5 колонок (ID скрыт): Code | Type | (Default) | Description | Constraints
+
+```html
+<table class="resource-table resource-table-compact resource-table-required">
+<thead><tr><th>ID</th><th>Code</th><th>Type</th><th>Description</th><th>Constraints</th></tr></thead>
+```
+
+### Nested (map-fixed/array-map-fixed)
+
+7 колонок: ID | Code | Type | Required | Default | Description | Constraints
+ID скрыт, Required — ★ для непустых ячеек.
+
+```html
+<table class="resource-table resource-table-compact resource-table-nested">
+<thead><tr><th>ID</th><th>Code</th><th>Type</th><th>Required</th><th>Default</th><th>Description</th><th>Constraints</th></tr></thead>
+```
+
+## CSS (глобальный, `docs/30_registry/assets/extra.css`)
+
+| Элемент | Правило |
+|---|---|
+| ID колонка | `display: none` |
+| Required | `td:not(:empty)::before { content: "★"; color: #e74c3c; }` |
+| Code | 25% (main), 19% (nested), жирный |
+| Type | 5%, 0.63rem |
+| Default | 6% (nested), синий `#2c6f8c` |
+| Description | line-clamp(2) на `td`, мелкий серый |
+| Constraints | monospace 0.62rem, `word-break: break-word` |
+| thead | sticky, nowrap, 0.72rem |
+| tbody | zebra `tr:nth-child(even) { #fafafa }` |
+| MAN | `.man-content { font-size: 0.62rem; }` |
+| Заголовок h1 | 0.77rem |
+| Табы p | 0.65rem |
+| **Важно** | Все селекторы с префиксом `.md-typeset` |
+
+## mkdocs.yml
+
+Добавить в `markdown_extensions`:
+```yaml
+markdown_extensions:
+  - md_in_html
+```
+
+## Генератор (`TOOLS/docs-generator/internal/writers/writers.go`)
+
+Функции для правки:
+- `buildHeader()` — заголовок + табы (одна строка, `·`, активная жирным)
+- `buildManualPage()` — MAN в `<div class="man-content" markdown="1">`
+- `renderParamTable()` — классы таблиц
+- `renderModifyTable()` — модифай без лишних колонок если пустые
+
+## Порядок генерации
+
+1. Правим `writers.go`
+2. `cd TOOLS/docs-generator && go build -o ../bin/docs-generator .`
+3. `./02_generate_resources_and_docs_v2.sh --profile TOOLS/config/test`
+4. `mkdocs build` или `./04_build_and_publish_docs.sh`