Анализ ширины колонок таблиц документации

Методика определения оптимальных ширин колонок на основе реальных данных из YAML-спек.

Методика

Источник данных

Все параметры ресурсов генерируются из YAML-спек в generated/<stand>/resources_yaml/*.yaml. Скрипт анализа собирает ВСЕ параметры из всех YAML-файлов (только операции create и modify, включая вложенные sub_params).

Что измеряется

Для каждого параметра извлекаются 5 групп значений:

Группа	Поля YAML	Назначение в таблице
Code	`code`	Название параметра
Type	`data_type`, `type`	Тип данных
Default	`default`	Значение по умолчанию
Description	`descr`, `man`	Описание
Constraints	`min_value`, `max_value`, `regex`, `value_list`, `max_length`, `min_length`, `func`, `ref_svc_id`, `unique`	Ограничения

Для каждой группы вычисляется:

MAX длина строки (символов)
AVERAGE длина
% значений длиннее 30/50/100/200/500 символов

Код анализа

import os, yaml

YAML_DIR = 'generated/test/resources_yaml'
all_params = []
nested_count = 0

def extract_params(svc, op, params_list, depth=0):
    global nested_count
    for p in params_list:
        if not isinstance(p, dict): continue
        all_params.append((svc, op, p, depth))
        sub = p.get('sub_params', [])
        if sub:
            nested_count += len(sub)
            extract_params(svc, op, sub, depth + 1)

for fname in sorted(os.listdir(YAML_DIR)):
    if not fname.endswith('.yaml'): continue
    with open(os.path.join(YAML_DIR, fname)) as f:
        data = yaml.safe_load(f)
    svc = data.get('name', fname)
    for op in data.get('operations', []):
        if op.get('action') not in ('create', 'modify'): continue
        extract_params(svc, op.get('name','?'), op.get('params', []))

# ... (статистика по 5 группам, см. ниже)

Когда перезапускать анализ

После добавления новых сервисов
После изменения структуры параметров в API
При смене стенда (test/dev/prod)

Запуск:

python3 analyze_column_widths.py

Результаты (стенд test, 2026-07-18)

Объём данных: 49 YAML-файлов, 775 параметров, 339 вложенных sub_params

Колонка	Count	MAX (симв.)	AVG (симв.)	>50	>100	>200
Code	775	29	11	0%	0%	0%
Type	775	15	9	0%	0%	0%
Default	497	48	4	0%	0%	0%
Description	488	635	69	55%	25%	3%
Constraints	247	199	46	27%	6%	0%

Выводы

Code, Type, Default — всегда короткие (макс 48 символов, обычно < 15). Им не нужно много места.
Description — основная колонка. 55% значений > 50 символов, 25% > 100. Ей нужна бОльшая часть ширины.
Constraints — есть только у 32% параметров (247 из 775). Длинные regex (> 100 символов) — исключение (у mariadb, clickhouse, postgres). Не нужно раздувать колонку ради 6% случаев — хватит word-break: break-all.
Default — есть у 64% параметров, всегда короткий (AVG 4 символа).

Оптимальные ширины колонок

Используется table-layout: fixed — браузер жёстко соблюдает проценты.

Основная таблица (`.resource-table:not(.resource-table-nested)`)

Колонка	CSS-селектор	Ширина	Примечание
ID	`nth-child(1)`	3%
Code	`nth-child(2)`	15%
Type	`nth-child(3)`	7%
Default	авто	авто	только если есть (6 колонок)
Description	`nth-last-child(2)`	48%	главная колонка
Constraints	`nth-last-child(1)`	27%	`word-break: break-all`

Nested-таблица (`.resource-table-nested`)

Колонка	CSS-селектор	Ширина	Примечание
ID	`nth-child(1)`	3%
Code	`nth-child(2)`	12%
Type	`nth-child(3)`	7%
Required	`nth-child(4)`	5%
Default	`nth-child(5)`	7%
Description	`nth-child(6)`	38%	главная колонка
Constraints	`nth-child(7)`	28%	`word-break: break-all`

Принцип

Если поле широкое только в 5% случаев — не надо рисовать его широким для всех. Description — всегда широкий. Constraints — редко широкий, пусть ломается.

5.5 KiB Raw Blame History Unescape Escape