diff --git a/Soft/Notes/auto-note.html b/Soft/Notes/auto-note.html index fb58a19..782201a 100644 --- a/Soft/Notes/auto-note.html +++ b/Soft/Notes/auto-note.html @@ -2,57 +2,30 @@ title: Автоматизации написания документации description: published: true -date: 2023-11-15T16:22:07.682Z +date: 2023-11-15T16:23:59.264Z tags: editor: ckeditor dateCreated: 2023-11-15T16:22:07.682Z --> -
-

Я неоднократно в заметках обозревал инструменты для ведения документации. Вот примеры продуктов:
▪️ MkDocs (https://t.me/srv_admin/2099) - инструмент для генерации документации в виде статического сайта на базе текстовых файлов в формате markdown.
▪️ BookStack (https://t.me/srv_admin/2096) - open source платформа для создания документации и вики-контента.
▪️ Wiki.js (https://t.me/srv_admin/561) - готовая wiki платформа с поддержкой редакторов wiki, markdown, wysiwyg.

-

Сегодня хочу рассказать про ещё один инструмент для автоматизации написания документации. А конкретно по её визуализации с помощью схем и диаграмм. Речь пойдёт про Mermaid. Это известный и популярный инструмент для создания визуализаций и диаграмм на основе написанного кода.

-

Основная идея Mermaid в том, что вы пишите текст, а на выходе получаете визуализацию. Это позволяет решать целый спектр задач, таких как:
1. Автоматизация создания контента.
2. Совместная работа с контентом.
3. Простая и понятная схема сохранения истории изменений.

-

Для понимания наглядный пример. Вот такой текст:

-
- - - - - - -
-

graph TD;

-

A-->B;

-

A-->C;

-

B-->D;

-

C-->D;

-
-
-

Превращается в картинку с блок схемой и стрелочками. Посмотрите остальные примеры на главной странице проекта (https://mermaid-js.github.io/), чтобы сразу понять, какой это инструмент и что с его помощью можно нарисовать.

-

С помощью Mermaid можно автоматизировать создание и изменение схем, редактируя текст после изменения структуры объектов. Автоматически будет меняться и картинка. История изменений отслеживается, всегда можно посмотреть прошлый вариант.

-

Самый простой и наглядный пример, где это может пригодиться - описание взаимодействия микросервисов, прохождение пользовательских запросов. Это как раз решается на уровне рисования блок-схем со стрелочками. Наглядные примеры (https://www.kubernetes.dev/blog/2021/12/01/improve-your-documentation-with-mermaid.js-diagrams/) с официального блога kubernetes.

-

На практике применение выглядит следующим образом. К примеру, github нативно поддерживает диаграммы Mermaid.js в README-файлах. Можно прямо в них писать код и он будет отрисовываться в картинки. Также Mermaid.js нативно интегрирована в GitLab, Gitea (https://t.me/srv_admin/1370), Joplin (https://t.me/srv_admin/1563) и Notion. Для многих сервисов есть плагины. А в общем случае это пакет для nodejs, который можно поставить локально через nmp, запускать как сервис и обращаться к нему или с помощью CLI прогонять через него текстовые данные:

-
- - - - - - -
-

npm install -g mermaid

-

npm install -g @mermaid-js/mermaid-cli

-

mmdc -i scheme.mmd -o scheme.png -w 1024 -H 768

-
-
-


Или с помощью Docker:

-
- - - - - - -
docker run -it -v ~/diagrams:/data minlag/mermaid-cli -i /data/diagram.mmd
-
-


 

+
+

Я неоднократно в заметках обозревал инструменты для ведения документации. Вот примеры продуктов:
▪️ MkDocs (https://t.me/srv_admin/2099) - инструмент для генерации документации в виде статического сайта на базе текстовых файлов в формате markdown.
▪️ BookStack (https://t.me/srv_admin/2096) - open source платформа для создания документации и вики-контента.
▪️ Wiki.js (https://t.me/srv_admin/561) - готовая wiki платформа с поддержкой редакторов wiki, markdown, wysiwyg.

+

Сегодня хочу рассказать про ещё один инструмент для автоматизации написания документации. А конкретно по её визуализации с помощью схем и диаграмм. Речь пойдёт про Mermaid. Это известный и популярный инструмент для создания визуализаций и диаграмм на основе написанного кода.

+

Основная идея Mermaid в том, что вы пишите текст, а на выходе получаете визуализацию. Это позволяет решать целый спектр задач, таких как:
1. Автоматизация создания контента.
2. Совместная работа с контентом.
3. Простая и понятная схема сохранения истории изменений.

+

Для понимания наглядный пример. Вот такой текст:

+
graph TD;
+A-->B;
+A-->C;
+B-->D;
+C-->D;
+

Превращается в картинку с блок схемой и стрелочками. Посмотрите остальные примеры на главной странице проекта (https://mermaid-js.github.io/), чтобы сразу понять, какой это инструмент и что с его помощью можно нарисовать.

+

С помощью Mermaid можно автоматизировать создание и изменение схем, редактируя текст после изменения структуры объектов. Автоматически будет меняться и картинка. История изменений отслеживается, всегда можно посмотреть прошлый вариант.

+

Самый простой и наглядный пример, где это может пригодиться - описание взаимодействия микросервисов, прохождение пользовательских запросов. Это как раз решается на уровне рисования блок-схем со стрелочками. Наглядные примеры (https://www.kubernetes.dev/blog/2021/12/01/improve-your-documentation-with-mermaid.js-diagrams/) с официального блога kubernetes.

+

На практике применение выглядит следующим образом. К примеру, github нативно поддерживает диаграммы Mermaid.js в README-файлах. Можно прямо в них писать код и он будет отрисовываться в картинки. Также Mermaid.js нативно интегрирована в GitLab, Gitea (https://t.me/srv_admin/1370), Joplin (https://t.me/srv_admin/1563) и Notion. Для многих сервисов есть плагины. А в общем случае это пакет для nodejs, который можно поставить локально через nmp, запускать как сервис и обращаться к нему или с помощью CLI прогонять через него текстовые данные:

+
npm install -g mermaid
+npm install -g @mermaid-js/mermaid-cli
+mmdc -i scheme.mmd -o scheme.png -w 1024 -H 768
+


Или с помощью Docker:

+
docker run -it -v ~/diagrams:/data minlag/mermaid-cli -i /data/diagram.mmd
+

 

+