32 lines
5.1 KiB
HTML
32 lines
5.1 KiB
HTML
<!--
|
||
title: Автоматизации написания документации
|
||
description:
|
||
published: true
|
||
date: 2023-11-15T16:23:59.264Z
|
||
tags:
|
||
editor: ckeditor
|
||
dateCreated: 2023-11-15T16:22:07.682Z
|
||
-->
|
||
|
||
<figure class="image"><img src="/attachments/image2022-8-16_9-23-0.png"></figure>
|
||
<p>Я неоднократно в заметках обозревал инструменты для ведения документации. Вот примеры продуктов:<br>▪️ MkDocs (<a href="https://t.me/srv_admin/2099">https://t.me/srv_admin/2099</a>) - инструмент для генерации документации в виде статического сайта на базе текстовых файлов в формате markdown.<br>▪️ BookStack (<a href="https://t.me/srv_admin/2096">https://t.me/srv_admin/2096</a>) - open source платформа для создания документации и вики-контента.<br>▪️ Wiki.js (<a href="https://t.me/srv_admin/561">https://t.me/srv_admin/561</a>) - готовая wiki платформа с поддержкой редакторов wiki, markdown, wysiwyg.</p>
|
||
<p>Сегодня хочу рассказать про ещё один инструмент для автоматизации написания документации. А конкретно по её визуализации с помощью схем и диаграмм. Речь пойдёт про Mermaid. Это известный и популярный инструмент для создания визуализаций и диаграмм на основе написанного кода.</p>
|
||
<p>Основная идея Mermaid в том, что вы пишите текст, а на выходе получаете визуализацию. Это позволяет решать целый спектр задач, таких как:<br>1. Автоматизация создания контента.<br>2. Совместная работа с контентом.<br>3. Простая и понятная схема сохранения истории изменений.</p>
|
||
<p>Для понимания наглядный пример. Вот такой текст:</p>
|
||
<pre><code class="language-plaintext">graph TD;
|
||
A-->B;
|
||
A-->C;
|
||
B-->D;
|
||
C-->D;</code></pre>
|
||
<p>Превращается в картинку с блок схемой и стрелочками. Посмотрите остальные примеры на главной странице проекта (<a href="https://mermaid-js.github.io/">https://mermaid-js.github.io/</a>), чтобы сразу понять, какой это инструмент и что с его помощью можно нарисовать.</p>
|
||
<p>С помощью Mermaid можно автоматизировать создание и изменение схем, редактируя текст после изменения структуры объектов. Автоматически будет меняться и картинка. История изменений отслеживается, всегда можно посмотреть прошлый вариант.</p>
|
||
<p>Самый простой и наглядный пример, где это может пригодиться - описание взаимодействия микросервисов, прохождение пользовательских запросов. Это как раз решается на уровне рисования блок-схем со стрелочками. Наглядные примеры (<a href="https://www.kubernetes.dev/blog/2021/12/01/improve-your-documentation-with-mermaid.js-diagrams/">https://www.kubernetes.dev/blog/2021/12/01/improve-your-documentation-with-mermaid.js-diagrams/</a>) с официального блога kubernetes.</p>
|
||
<p>На практике применение выглядит следующим образом. К примеру, github нативно поддерживает диаграммы Mermaid.js в README-файлах. Можно прямо в них писать код и он будет отрисовываться в картинки. Также Mermaid.js нативно интегрирована в GitLab, Gitea (<a href="https://t.me/srv_admin/1370">https://t.me/srv_admin/1370</a>), Joplin (<a href="https://t.me/srv_admin/1563">https://t.me/srv_admin/1563</a>) и Notion. Для многих сервисов есть плагины. А в общем случае это пакет для nodejs, который можно поставить локально через nmp, запускать как сервис и обращаться к нему или с помощью CLI прогонять через него текстовые данные:</p>
|
||
<pre><code class="language-plaintext">npm install -g mermaid
|
||
npm install -g @mermaid-js/mermaid-cli
|
||
mmdc -i scheme.mmd -o scheme.png -w 1024 -H 768</code></pre>
|
||
<p><br>Или с помощью Docker:</p>
|
||
<pre><code class="language-plaintext">docker run -it -v ~/diagrams:/data minlag/mermaid-cli -i /data/diagram.mmd</code></pre>
|
||
<p> </p>
|
||
<p><br> </p>
|