“Naeel”
c9a881aa84
- value_list → читаемый текст (Допустимые значения) - regex → описание формата - пустые описания → заполнять из MAN - группы map-fixed → 1 предложение о содержимом - операции без описания → шаблоны - MAN-контекст для params/ops файлов - max_tokens 4096 → 8192 - вывод в docs_llm/ вместо перезаписи docs/
2.4 KiB
2.4 KiB
Документация — полный диалог и финальный план
Ответы на 3 вопроса Соннета
1. Inline-навигацию убирать?
Убирать, но сначала добавить страницы в sidebar.
Сейчас ресурсные страницы не в mkdocs.yml nav: — они сироты. Inline nav — единственная навигация.
Порядок: сначала P3 (добавить в sidebar через _nav_fragment.yml), потом убрать inline из writers.go.
2. Минимальный пример — только required без default?
Да. Параметр с дефолтом и так сработает без указания. Минимальный пример = required=true И default пустой. 15 строк вместо 100.
3. Категории для sidebar
Группировка по 7 категориям:
| Категория | Сервисы |
|---|---|
| Базы данных | postgres, redis, mongodb, mariadb, clickhouse |
| Очереди | rabbitmq, kafka |
| Хранилище | s3, s3bucket, nextcloud |
| K8s | k8s_velero, k8s_sthutrval_cluster, k8s_openbao, vc_mgmt_sthutrval_cluster |
| VMware | vc_org, vc_vdc, vc_nsxt, vcexternalip, vapp, vc_vm_v2, vc_vm_v3, vc_vdc_group |
| Приложения | flask, nodejs, lucee, http, gitea, superset, pgadmin, harbor, akhq, llm_ai |
| Сеть | zones_v2, dnsrecord |
Финальный план (3 слоя)
P1: LLM-промпт (05_generate_docs_llm.py) — 0 компиляции, 34 сервиса
6 инструкций:
- value_list → «Допустимые значения: X, Y, Z»
- regex → «Формат: cron / UUID / IP»
- Описания групп из MAN
- Пустые описания заполнять
- Операции без «—»
- TODO в примерах → реальные значения
P2: docs-generator (writers.go)
- renderParamTable: убрать ID, value_list → читаемый текст
- buildExamplePage: минимальный пример + полный в
P3: mkdocs навигация
- docs-generator генерирует _nav_fragment.yml с категориями
- 04_build_and_publish_docs.sh вставляет его в mkdocs.yml
- writers.go: убрать inline nav
- mkdocs.yml: breadcrumbs + prev/next