0015 — Material for MkDocs и среда developer docs¶

Дата: 2026-08-22.
Статус: Частично заменено; технология остаётся принятой, имя домена заменено решением 0019, Basic Auth policy заменена решением 0030.
Ответственный: владелец проекта.

Актуальная access policy определена решением 0030: developer docs доступны для тестов без Basic Auth. Ниже сохранён исторический контекст выбора.

Контекст¶

Для user docs и developer docs уже принят отдельный приватный репозиторий webuzateam/SkuAro-Docs. Первоначально был выбран VitePress. После отдельного обсуждения владелец выбрал Material for MkDocs как более подходящий для Markdown-ориентированной технической документации.

Решение¶

Стек Docs-репозитория — open-source Material for MkDocs 9.x без зависимости от Insiders-функций.
Точная версия Python-зависимостей фиксируется lock-файлом и container image.
Developer docs собираются в статический артефакт и публикуются на doc-dev.skuaro.top.
doc-dev.skuaro.top является отдельным Compose-контуром skuaro-doc-dev, не имеет доступа к базе данных продукта и защищается Basic Auth и noindex.
Публикация developer docs и user docs имеет независимые сборки и deploy, даже если они живут в одном Docs-репозитории.
OpenAPI и другие связанные с кодом артефакты генерируются из product-репозитория; вручную в двух местах не поддерживаются.
Связанная с кодом модульная документация может оставаться в modules/<module-id>/docs; Docs-сайт публикует её как версионированный артефакт без ручного дублирования.

Проверки¶

До публикации обязательны build, link check, secret scan, проверка mobile/keyboard navigation, поиска, Basic Auth, noindex и отсутствия секретов в собранном артефакте.

Последствия¶

Ссылки на VitePress в канонических документах заменяются.
Создание webuzateam/SkuAro-Docs, добавление Python/Docker-зависимостей, изменение сервера и deploy остаются отдельными внешними действиями.
До создания Docs-репозитория полный сайт не создаётся временно в product-репозитории.

Откат или замена¶

Смена генератора документации, границ публикации или модели источников истины требует нового ADR и плана миграции.