В Промсвязьбанке накопилось несколько версий документации для внутреннего CI/CD-модуля: часть жила в readme-репозитории, часть — на корпоративном портале. Обе устарели и были заброшены, потому что обновлять их вручную никто не успевал. iOS-разработчик Николай Чурянин решил задачу иначе: сделать так, чтобы документация жила прямо в коде и обновлялась сама.
Главное ограничение — CI/CD-модуль банка использует сразу четыре типа файлов: yml-конфигурации, bash-, Python- и Ruby-скрипты. Готовые генераторы документации — такие как Doxygen, Sphinx или аналоги — либо заточены под конкретный язык, либо требуют разного синтаксиса для каждого типа файлов. Это означало бы несколько разрозненных документов вместо одного. Чурянин выбрал другой путь: написать собственный парсер с помощью генеративной модели.
| Тип файла | Способ извлечения комментария |
|---|---|
| yml-конфигурация | Комментарий перед элементом массива или объектом |
| bash (.sh) | Комментарий с тегом @doc |
| Python (.py) | Комментарий с тегом @doc |
| Ruby (.rb) | Комментарий с тегом @doc |
Для yml-файлов логика простая: комментарий берётся непосредственно перед любым элементом массива или объектом. Для скриптов введён специальный тег @doc — только помеченные им блоки попадают в итоговую документацию. Это позволяет не засорять код лишними метаданными и при этом гибко управлять тем, что окажется в документе. Несколько тегов @doc в одном файле формируют отдельные блоки описания.
Для скриптов используется тег @doc — только помеченные комментарии попадают в документацию.
Результат генерации — HTML-страница. Выбор в пользу HTML, а не Markdown, объясняется прагматично: файл документации всё равно не редактируется вручную, зато HTML позволяет реализовать поиск, навигацию по секциям и удобную визуализацию. Страница разбита на разделы: этапы пайплайна, переменные (с названиями, значениями и описаниями), шаблоны, задания и скрипты. Поиск работает по подстроке — можно найти все задания конкретного этапа или все места, где вызывается определённый скрипт.
Жизненный цикл изменений теперь выглядит так: разработчик вносит правки в код вместе с комментариями, создаёт merge request — ревьювер уже на этом этапе видит, как изменится документация, — после слияния в master CI/CD автоматически запускает генерацию и коммитит обновлённый HTML обратно в репозиторий. Вся цепочка не требует ручного вмешательства.
Подход не уникален по идее — документирование через аннотации в коде используется давно: JavaDoc появился ещё в 1995 году, а современные инструменты вроде Sphinx для Python или YARD для Ruby работают по схожему принципу. Особенность решения ПСБ — унификация синтаксиса для разнородного стека и встраивание генерации непосредственно в CI/CD-пайплайн. Шесть скриптов, написанных в диалоге с генеративной моделью, закрыли задачу, которую готовые инструменты решить не смогли.
