Привет, Хабр! Меня зовут Николай Чурянин, я занимаюсь iOS-разработкой в ПСБ. Сегодня я хочу рассказать вам, как делал новую документацию для нашего модуля CI/CD. Конечно же, документация у нас была и раньше. И даже не одна — а это, как понимаете, только усугубляло проблему. Часть документации лежала в readme-репозитории — с него-то она по сути и началась. Но обновлялась она там нерегулярно, оказалось, что работать с ней было не очень-то удобно. В какой-то момент этот репозиторий перестали поддерживать, и я попытался оформить её на внутреннем портале. Увы, пользы от этого стало ещё меньше: там документация была оторвана от кода — от наших скриптов. Вдобавок, её было трудно обновлять. Надо ли говорить, что и её забросили?

«Совсем без документации тоже нельзя», —  решил я и принялся искать другой способ. И нашёл его (спойлер: без ИИ тут не обошлось). Покажу, что получилось и как всё теперь работает. 

Начнём. Какая документация нам была нужна? Всё просто — актуальная, близкая к коду, функциональная и удобная для пользования и обновления.

Посмотрев на эти требования, я понял, какое решение им отвечает. Такое, что автоматически генерировало бы документацию из комментариев к коду. 

Обновляется код — обновляется дока. Удобно.

Что для этого нужно было сделать:

• сопровождать исходный код структурированными комментариями;

• парсить исходники, чтобы получать эти комментарии;

• формировать из полученных комментариев удобную документацию.

При этом было важно, чтобы и комментарии были очень простые, и при этом их простота не мешала читать код.

Теперь, когда был понятен механизм формирования документации, оставалось подобрать для него парсер исходных файлов. Всего лишь… Но это оказалось не так просто.

А не взять ли готовое решение?

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

Мы в CI/CD используем 4 вида файлов: yml-конфигурации, а также скрипты bash, Python и Ruby. И я, к сожалению, не нашёл инструмента, который поддерживал бы сразу все эти файлы. Использовать для каждого типа отдельный узкоспециальный инструмент? Тоже плохая идея, потому что тогда в каждом файле будет свой синтаксис. А в итоге — разные результирующие файлы. Работать с такой документацией будет очень тяжело.

Итого: мне нужно было самому закатывать рукава и писать решение… Ладно, не совсем самому: в нашу эпоху работу можно поручить «новому другу» — нейросети.

Техническая реализация

Чтобы сделать задуманное, нужно было решить несколько моментов.

Структурированные комментарии. Если смотреть именно наши файлы, то комментарии в них можно разделить на два типа (я их уже упоминал):

• Файл конфигурации (.yml)

• Три вида файлов скриптов (.sh, .py, .rb)

С файлами конфигурации всё довольно просто: понятно, какие данные могут быть в .yml, и можно без проблем взять комментарии непосредственно перед любым элементом массива или перед объектом.

А вот с файлами-скриптами уже немножко сложнее. Досконально парсить каждый тип дорого, а главное — и не нужно. Потому я решил здесь использовать  тег "@doc", который будет показывать, что данный комментарий должен попасть в результирующую документацию.

В какой тип файла будет генерироваться документация? Тут тоже были варианты, пришлось выбирать.

Я рассматривал два типа файлов — md и html. У каждого из них свои плюсы и минусы.

Какие преимущества у md-файла? Он очень простой, его легко редактировать вручную. Но придётся мириться и с недостатками — например, с крайне минималистичным видом обычного текстового файла. Есть и другая проблема — в тексте бывают свои символы форматирования, теги, которые могут отвлекать и сбивать с толку тех, кто пользуется документацией.

Ладно, а что с html? Его сильная сторона — настраиваемая визуализация. В файле можно реализовать разные дополнительные фичи, кастомизировать его, «сделать красиво», понятно, удобно и так далее. Минусы? Тоже есть — и в первую очередь, сложность с редактированием вручную. Не каждый разработчик вообще поймёт, что там внутри. И сам файл — огромный. Но здесь есть и хороший момент: нам-то ведь и не нужно редактировать файл документации вручную, потому что мы будем использовать генератор.

Поэтому в итоге выбрал для документации html-файл.

Что получилось?

Спустя несколько незабываемых итераций общения с ИИ, расписывать которые смысла нет (кто пробовал — те сами представляют), я получил шесть файлов скриптов. Они и дают весь тот функционал, который мы определили раньше.

Документация представляет собой страничку, где отображается различная информация:

Здесь есть дата генерации, разные сводные данные, поиск и секции: по этапам пайплайна, переменным, шаблонам, заданиям и скриптам.

Дальше я немного расскажу про каждую секцию.

Этапы пайплайна — это стадии. Справа вверху можно видеть, как это выглядит в коде.

Секция переменных. Здесь содержатся названия переменных, их значения и файл, в котором они находятся, и описания. И снова — наверху в коде видно, что описание документация берёт из комментария над переменной.

Шаблоны. Страница содержит подробную информацию о них: название шаблона, конфигурацию и так далее. Есть поддержка списков.

Задания. Здесь почти всё то же, что и в секции шаблонов.

Скрипты. Здесь несколько вкладок. Есть статистика по файлам. На скриншоте — пример для скрипта Ruby. Давайте посмотрим, как это выглядит в коде.

Здесь мы используем тег @doc. Тогда всё, что находится в комментарии после тега и не отделено переносом, попадает в результирующую документацию. Как видно из кода, мы можем использовать несколько тегов — они тоже будут разделены в описании своими блоками, и это очень удобно.

В нашей документации также реализован поиск по странице. Допустим, мы хотим найти, какие именно задания выполняются на том или ином этапе пайплайна. Можно скопировать название нужного этапа, вставить его в поиск — и в результатах будет видно, где используется эта подстрока. Как правило, если название взять целиком, то оно больше нигде не совпадает. Поэтому поиском мы находим все задания шаблона данного этапа.

Или вот ещё пример — поиск по скрипту. С его помощью мы можем  посмотреть, где используется скрипт: увидим все шаблоны и задания, где данный скрипт вызывается.

Ещё можно искать по слову. Например, я пишу “coverage” — и вижу, что есть связанный с ним этап, переменная, шаблоны, задания и так далее.

А генерит-то кто?

Как страница документации выглядит и что умеет, мы разобрались. Теперь возникает другой важный вопрос : а кто эту документацию генерирует? А CI/CD и будет это делать. Например, здесь видно, что после залития merge квеста в мастер запускается пайплайн, который генерирует заново нашу документацию, коммитит её назад в мастер.

Жизненный цикл изменений при работе с CI/CD сейчас выглядит так:

• Изучение новой доработки CI/CD;

• Реализация доработки;

• Создание запроса на слияние (на данном этапе ревьювер видит, как изменится документация, и может попросить что-то дописать)

• Вливание в master;

• Обновление документации в master.

Стоило ли оно того?

Новая страница документации отняла немало времени, заставила подумать над требованиями, повозиться с генеративной моделью… а ради чего? Реально ли от неё теперь есть польза и стало лучше, чем было? Давайте посчитаем плюсы текущего решения:

• Легко поддерживать документацию. Уже не надо вести её вручную, куда-то ходить — потому что документация у нас прямо в коде;

• Быстрая навигация по документации. Теперь легко найти, где что используется;

• Бонус — альтернативный взгляд на модуль CI/CD. Так вышло (не специально), что, когда я первый раз занимался этим решением, то обнаружил некоторые проблемы, на которые потом завели задачи улучшения.

В общем, я доволен тем, что получилось.

Подытожим