tgoop.com/eshu_coding/368
Last Update:
Познакомился с занятным инструментом для рисования графиков в документации к коду не выходя из гита. Самый простой способ что-то написать про проект - вписать это в Readme в формате markdown. У этого формата есть расширение для формирования иллюстраций - Mermaid.
Делаешь специальный блок в документе и пошёл описывать контент иллюстрации на чем-то напоминающем декларативный язык программирования. Задал основные объекты, ниже описал связи - получил симпатичную иллюстрацию. Расстановкой элементов графика занимается автоматика, от пишущего документацию требуется только накидать контент.
Очень удобно сделать отдельную ветку для документации прямо в интерфейсе гитлаба/гитхаба и там же править документ, переключаясь между вкладками Edit и Preview. Первые несколько подходов у меня текла кровь из глаз по попытке разобраться в коде, формирующем иллюстрации. Но когда отодвигать погружение стало некуда - на первичное освоение инструмента ушло около 30 минут.
Раньше я делал схемы и иллюстрации к проектам как завещали деды учили в универе: открываем inkscape и рисуем векторную картинку. С новым для меня инструментом все стало в разы быстрее. А в дополнение мы получаем все плюшки гита: версионирование и лог всех изменений с возможностью быстрого отката на старые версии.
В качестве примера попробовал набросать иллюстрацию схемы сервисов абстрактной системы, включающей две базы данных, фронтенд, апишку, брокер сообщений, телеграм бота и сервис - обработчик данных. На все ушло минут 5, получилась вполне пристойная картинка. Ниже приведен "код", формирующий иллюстрацию:
flowchart TD
mainDb[(PostgreSQL)]
botDb[(PostgreSQL)]
api[API]
service[Worker Service]
botService[Telegram Bot]
broker[[RabbitMQ]]
frontend[Frontend]
botService --> botDb
api ---> mainDb
service ---> mainDb
frontend --"REST"--> api ---> broker --> service
service ---> broker
botService ---> broker
broker ---> botService
Видов возможных диаграмм масса, можно подобрать себе тип под любую задачу, связанную с документированием процесса разработки.
P.S. Из забавного - в гите не предусмотрели возможности скопировать диаграмму отдельно как картинку.
BY Эшу быдлокодит
Share with your friend now:
tgoop.com/eshu_coding/368