Битва с эталоном: Как sidebar.toml спас нас от хардкода структуры
· 3 min read
Пока мы проектировали будущие нативные парсеры, на работе задачу по переходу на Flude никто не отменял. И там были свои корпоративные сложности.
У бизнеса было одно железобетонное условие: миграция на Flude должна пройти абсолютно прозрачно. Наш вывод (пока еще работающий на базе Doxygen) должен был один в один совпадать с выводом старого генератора документации как по полноте, так и по структуре страниц, включая точные имена генерируемых HTML-файлов.
Разная философия структуры
Проблема заключалась в фундаментальной разнице философии рендереров. Современный подход в генерации документации подразумевает, что весь класс (со всеми его свойствами и методами) рендерится на одной цельной странице. Навигация внутри класса происходит через обычные HTML-якоря (например, class.html#MethodName).
Старый генератор работал совершенно иначе: для каждого отдельного метода, свойства и члена класса он создавал свою крошечную, отдельную HTML-страницу.
Если бы мы применили современный подход, мы бы разом сломали кучу старых ссылок, закладок и внутренних интеграций, к которым годами привыкали инженеры компании. Нам нужно было во что бы то ни стало эмулировать эту легаси-структуру.
Декларативный sidebar.toml
Для специфичных нужд компании у нас был выделен отдельный закрытый плагин. Но я категорически не хотел хардкодить логику “расщепления” страниц даже туда. Изначальный план был таким: вынести логику в гибкие настройки, а если это хорошо заработает — перенести фичу в основное ядро.
Решением стал конфигурационный файл sidebar.toml. Он позволил вручную настраивать правила формирования навигационного меню и гибко управлять тем, как логическая структура кода будет маппиться на физическую файловую систему и структуру самой документации. Этот манифест позволил не хардкодить аутпут, а держать его полностью в конфигурации.
Перенос в основное ядро
Эксперимент оказался невероятно удачным. Отвязать физическую структуру вывода от внутренней архитектуры парсера — это мощнейший паттерн.
Как и планировалось, мы перенесли механику sidebar.toml из рабочего плагина в основное ядро Flude, сделав её абсолютным стандартом для генерации любых проектов.
SaaS-Ограничения
Правда, есть один нюанс. Несмотря на то, что ядро теперь поддерживает генерацию любой кастомной структуры через sidebar.toml, в нашей облачной SaaS-версии мы пока не даем пользователям такой свободы.
Наши облачные воркеры используют статический файл sidebar.toml, который мы сами кладем на сервер. Пользователь просто не имеет к нему доступа и не может передать свой конфиг извне. В текущей версии SaaS возможность изменения конфигурации структуры заблокирована. Но главное, что архитектурный фундамент под нее уже надежно заложен в ядре.
Итог
С помощью конфигурации мы успешно отвязали структуру аутпута от структуры парсера и полностью удовлетворили рабочие требования по ссылкам.
Но для успешной сдачи проекта оставалась еще одна визуальная проблема. Старый генератор умел рисовать диаграммы наследования классов в формате PNG, и нам нужно было повторить этот функционал. О том, как мы реализовывали генерацию картинок и почему эта фича тоже переехала в ядро — читайте в следующем эпизоде.