Некоторая часть документации werf генерируется автоматически из описания cobra-комманд.
По умолчанию форматирование текста в справочных данных команд расчитано на командрую строку, чтобы при вызове команды help было удобно читать в терминале появившийся текст.
При этом сгенерированные из такого текста файлы Markdown представляют собой неформатированный текст, который на сайте выгядит крайне неуместно.
Доработка генератора включала в себя несколько шагов:
- Создание механизма, осуществляющего нормальную генерацию Markdown-файлов. Для этого было сделано следующее:
- Вся документация была сложена в отдельные файлы для каждой команды с разделением на два типа: для
helpи для Markdown; - Документация для
helpвызывается из созданной структуры и как обычно прикрепляется к cobra-комманде; - На каждую команду навешивается аннотация, содержащая отформатированную для Markdown документацию;
- В генераторе добавлен механизм, который проверяет, существует ли аннотация с MD. В случае, если она есть, на генерацию отдается отформатированный текст, если же ее нет — срабатывает штатный механизм, генерирующий документацию из
help.
- Вся документация была сложена в отдельные файлы для каждой команды с разделением на два типа: для
Такой кодход отлично сработал для собственных команд, но в составе утилиты присутствуют и заимствованные из других пакетов.
Для них были подготовлены «реплейсеры» — функции, перехватывающие создание заимствованных команд и навешивающие на них правильно отформатированную документацию.
Здесь все разделилось на два глобальных шага:
- В одном случае (команды Helm) было достаточно просто перехватывать команды;
- Во втором (команды kubectl) все команды были вложены друг в друга, начиная с одной верхней, поэтому решением стала красивая рекурсивная функцию, переберающая все команды и навешивающая на них нужные аннотации.
Чтобы убедиться, что все реплейсеры правильно отработали, были написаны Unit-тесты, проверяющие как наличие аннотации на каждой из команд, так и содержимое документации в них.
Все работы можно посмотреть в этих PR’ах на GitHub:
- Fix the documentation generator up to the “Helper commands” section
- Refactor docs generator: add longMD into Annotations
- Refactor docs generator: add graceful formatting of shorts in compose commands
- Fix docs generator in remaining commands
- Replace helm docs
- Replace helm docs, part 2
- Add Unit tests to the Helm documentation replacers
- Fixing the documentation generator in kubectl commands
UPD: Тесты отработали как надо — при обновлении зависимостей прилетели новые подкоманды kubectl, на них не прилепились аннотации, тесты упали.
Подробнее в PR #5399: Fix documentation generator