Руководство по документации

Каждая функция должна быть задокументирована. Изменение не считается завершённым, пока документация не отражает его. Эта страница объясняет, как собирается сайт документации и как добавлять или обновлять страницы — включая синхронизацию английской и русской версий.

Стек

Сайт собран с Material for MkDocs плюс mkdocs-static-i18n для двуязычного контента. Конфигурация — в mkdocs.yml в корне репозитория; закреплённый набор инструментов — в docs/requirements.txt.

Почему не Zensical?

Преемник от команды Material for MkDocs с конфигурацией на TOML — Zensical — рассматривался (его упоминал мейнтейнер). По состоянию на 2026 его рабочий процесс с контентом на нескольких языках находится в дорожной карте, но ещё не реализован, поэтому он пока не может поддерживать параллельные деревья страниц EN/RU с переключателем языка. Двуязычная документация — жёсткое требование, поэтому мы используем зрелый стек Material + i18n (тот же, что у FastStream и AG2). Миграция на Zensical позже — поддерживаемый, почти механический путь.

Локальная сборка и предпросмотр

python -m pip install -r docs/requirements.txt
mkdocs serve          # предпросмотр с живой перезагрузкой на http://127.0.0.1:8000
mkdocs build --strict # то, что запускает CI; падает на предупреждениях (битые ссылки и т.д.)

Структура папок

Документация использует папочную двуязычную структуру: у каждого языка своё зеркальное дерево под docs/.

docs/
  en/                         # английский — основное, авторитетное дерево
    index.md
    getting-started/
    architecture/
      contexts/
    reference/
    contributing/
  ru/                         # русский — зеркалит en/; непереведённые страницы откатываются на en/
  design/                     # внутренние проектные записи (например, модель угроз)
  requirements.txt

• docs/en/** — авторитетно. Пишите или обновляйте сначала английский.
• docs/ru/** зеркалит те же пути. Страница, присутствующая в en/, но отсутствующая в ru/, автоматически откатывается на английский (fallback_to_default: true), так что сайт никогда не выдаёт 404 на непереведённой странице.

Добавление или изменение страницы

1. Отредактируйте/создайте английскую страницу под docs/en/....
2. Если это новая страница, добавьте её в nav: в mkdocs.yml (пути относительны языковой папке, например getting-started/configuration.md).
3. Если запись nav — новый заголовок раздела, добавьте его русский перевод в nav_translations блока языка ru плагина i18n в mkdocs.yml.
4. Зеркальте страницу по тому же пути под docs/ru/... с переведённым содержимым. Если вы пока не можете перевести, пропустите RU-файл — откат сохранит сайт валидным — но заведите follow-up, чтобы RU-дерево догнало.
5. Запустите mkdocs build --strict и исправьте предупреждения.

Синхронизация EN и RU

Практический рабочий процесс:

• Английский — источник истины. Каждое изменение контента сначала попадает в en/.
• Русскому зеркалу позволено отставать; откат предотвращает битые страницы.
• Отслеживайте долг перевода: когда страница en/ меняется, соответствующая страница ru/ устаревает до обновления. Помечайте устаревшие RU-страницы admonition вверху и/или отслеживайте их в описании PR, чтобы не забыть.
• Предпочитайте небольшие PR в пределах страницы, чтобы изменение EN и его перевод RU могли попасть вместе.

Двуязычная политика проверяется в CI

scripts/check-i18n.sh (задание i18n в workflow документации) на каждом PR контролирует две вещи:

• Структурное соответствие — у каждого docs/en/**/*.md должен быть парный docs/ru/**/*.md по зеркальному пути, и наоборот. Отсутствующий парный файл валит сборку.
• Страж дрейфа модели угроз — русский перевод docs/design/agate-proxy-threat-model.ru.md встраивает SHA git hash-object своего английского источника (docs/design/agate-proxy-threat-model.md) в комментарий <!-- en-source-sha: … -->. Если английская каноническая запись меняется, SHA перестаёт совпадать, и проверка падает, пока перевод не обновят, а встроенный SHA не перезапишут.

Диаграммы и код общие, не переводятся

Диаграммы Mermaid, блоки кода, идентификаторы, имена переменных окружения и команды CLI идентичны на всех языках — переводится только проза. Это делает два дерева дешёвыми в синхронизации.

Доступные средства оформления

• Admonitions: !!! note, !!! warning, !!! tip, !!! info, !!! abstract.
• Сворачиваемые блоки: ??? note.
• Вкладки контента: === "Вкладка".
• Диаграммы Mermaid: огороженные блоки ```mermaid.
• Подсветка кода + кнопка копирования: огороженные блоки кода с тегом языка.
• Включения-сниппеты: --8<-- "path" (используется страницей Модели угроз, чтобы подтянуть внутреннюю проектную запись, чтобы они никогда не расходились).