Починка генератора документации в werf | Zhbert’s Home
Zhbert's Home
Домашняя страничка Zhbert'а

Починка генератора документации в werf

Некоторая часть документации werf генерируется автоматически из описания cobra-комманд.

По умолчанию форматирование текста в справочных данных команд расчитано на командрую строку, чтобы при вызове команды help было удобно читать в терминале появившийся текст.

При этом сгенерированные из такого текста файлы Markdown представляют собой неформатированный текст, который на сайте выгядит крайне неуместно.

Доработка генератора включала в себя несколько шагов:

  • Создание механизма, осуществляющего нормальную генерацию Markdown-файлов. Для этого было сделано следующее:
    • Вся документация была сложена в отдельные файлы для каждой команды с разделением на два типа: для help и для Markdown;
    • Документация для help вызывается из созданной структуры и как обычно прикрепляется к cobra-комманде;
    • На каждую команду навешивается аннотация, содержащая отформатированную для Markdown документацию;
    • В генераторе добавлен механизм, который проверяет, существует ли аннотация с MD. В случае, если она есть, на генерацию отдается отформатированный текст, если же ее нет — срабатывает штатный механизм, генерирующий документацию из help.

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

Для них были подготовлены «реплейсеры» — функции, перехватывающие создание заимствованных команд и навешивающие на них правильно отформатированную документацию.

Здесь все разделилось на два глобальных шага:

  • В одном случае (команды Helm) было достаточно просто перехватывать команды;
  • Во втором (команды kubectl) все команды были вложены друг в друга, начиная с одной верхней, поэтому решением стала красивая рекурсивная функцию, переберающая все команды и навешивающая на них нужные аннотации.

Чтобы убедиться, что все реплейсеры правильно отработали, были написаны Unit-тесты, проверяющие как наличие аннотации на каждой из команд, так и содержимое документации в них.


Все работы можно посмотреть в этих PR’ах на GitHub: