Эшу быдлокодит

Познакомился с занятным инструментом для рисования графиков в документации к коду не выходя из гита. Самый простой способ что-то написать про проект - вписать это в 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. Из забавного - в гите не предусмотрели возможности скопировать диаграмму отдельно как картинку.

www.tg-me.com/us/Эшу быдлокодит/com.eshu_coding/368

533 viewsEshu Marabo, Feb 6, 2024 at 21:06

Познакомился с занятным инструментом для рисования графиков в документации к коду не выходя из гита. Самый простой способ что-то написать про проект - вписать это в 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

BY Эшу быдлокодит