В этой статье я шаг за шагом покажу вам, как создавать динамическую и интерактивную визуальную документацию с помощью инструментов «Диаграмма как код». Вместо статических изображений мы будем создавать диаграммы программным способом, гарантируя, что они всегда актуальны и просты в обслуживании.

? Диаграмма как код

Диаграмма как код — это подход, который позволяет создавать диаграммы с помощью кода вместо традиционных графических инструментов. Вместо построения диаграмм вручную вы можете написать код в текстовом файле, чтобы определить структуру, компоненты и связи ваших диаграмм.

Затем этот код переводится в графические изображения, что упрощает интеграцию и документирование в программных проектах, где он особенно полезен для программного создания и обновления архитектурных и блок-схем.

Что такое диаграммы?

Диаграммы — это ?библиотека Python, которая реализует подход «Диаграмма как код», позволяющий создавать диаграммы архитектурной инфраструктуры и другие типы диаграмм с помощью кода. С помощью диаграмм вы можете легко определить компоненты облачной инфраструктуры (такие как AWS, Azure и GCP), сетевые элементы, программные сервисы и многое другое, и все это с помощью всего лишь нескольких строк кода.

? Преимущества диаграммы как кода

• ? Представление диаграмм в виде кода: создавайте и обновляйте диаграммы непосредственно из кода, обеспечивая удобство сопровождения в гибких проектах.
• ? Автоматическое документирование: генерируйте визуальные эффекты из кода, сохраняя диаграммы в соответствии с текущей архитектурой.
• ? Управление изменениями: отслеживание изменений диаграммы с течением времени.
• ? Повышенная ясность: улучшите понимание сложных систем с помощью понятных и общих визуальных эффектов.
• ✏️ Настраиваемые: представляйте облачные инфраструктуры, рабочие процессы или конвейеры данных с помощью гибких и адаптированных визуальных эффектов.

Учебное пособие

? Установка библиотеки

В настоящее время для этого урока я использовал версию «0.23.4».

!pip install diagrams=='0.23.4'

? Диаграммы: узлы

Библиотека позволяет программно создавать архитектурные диаграммы, используя узлы для представления различных компонентов и сервисов инфраструктуры.

Типы узлов

Узлы на диаграммах представляют собой компоненты от разных поставщиков облачных услуг, а также другие архитектурные элементы. Вот основные категории доступных узлов:

• ☁️ Поставщики облачных услуг: AWS (Amazon Web Services), Azure, GCP, IBM Cloud, Alibaba Cloud, Oracle Cloud, DigitalOcean и другие.
• ? Локально: представляет инфраструктуру, физически расположенную на территории компании.
• ? Kubernetes (K8S): система оркестровки контейнеров для автоматизации развертывания, масштабирования и управления контейнерными приложениями (представлена ​​штурвалом, символизирующим управление и навигацию).
• ?️ OpenStack: программная платформа с открытым исходным кодом для создания и управления публичными и частными облаками.
• ? Общий: общие узлы, которые могут представлять любой компонент, не охваченный конкретно узлами, зависящими от поставщика (перекрещенные инструменты, представляющие разные инструменты в одной категории).
• ☁️ SaaS (программное обеспечение как услуга): представляет приложения, предоставляемые как услуга через Интернет, такие как Snowflake, службы чата (Slack, Teams, Telegram и другие), системы безопасности (например, Okta ) или социальные сети (для концепции SaaS зачеркнуты телефон и облако).
• ? Пользовательский: позволяет пользователям настраивать свои диаграммы с помощью значков PNG, хранящихся в определенной папке. Это полезно для представления компонентов инфраструктуры, не охваченных узлами по умолчанию (зачеркнутые пользовательские инструменты).

? Языки программирования

Библиотека Диаграммы позволяет использовать разные узлы для представления различных языков программирования. Эти узлы полезны для указания на ваших диаграммах, если какая-либо часть вашей архитектуры использует сценарии или компоненты, разработанные на определенном языке программирования.

Ниже мы покажем все доступные языки в библиотеке. Если какой-либо язык отсутствует, вы можете добавить собственные узлы, загрузив соответствующий логотип в определенную папку.

# Create the diagram object
with diagrams.Diagram("Programming Languages", show=False, filename="languages"):
    # Get all the languages available in this library
    languages = [item for item in dir(diagrams.programming.language) if item[0] != '_']

    # Divide the representation in two lines
    mid_index = len(languages) // 2
    first_line = languages[:mid_index]
    second_line = languages[mid_index:]

    # Add nodes in the first row
    prev_node = None

    for language in first_line:
        current_node = eval(f"diagrams.programming.language.{language}(language)")
        if prev_node is not None:
            prev_node >> current_node
        prev_node = current_node

    # Add nodes in the second row
    prev_node = None

    for language in second_line:
        current_node = eval(f"diagrams.programming.language.{language}(language)")
        if prev_node is not None:
            prev_node >> current_node
        prev_node = current_node

Image("languages.png")

☁️ AWS (Веб-сервисы Amazon)

Мы можем использовать узлы Amazon, которые разделены на несколько категорий, например:

• Аналитика и бизнес: aws.analytics, aws.business
• Вычисления и хранилище: aws.compute, aws.storage, aws.cost
• База данных и инструменты разработчика: aws.database, aws.devtools
• Интеграция и управление: aws.integration, aws.management
• Машинное обучение и мобильные устройства: aws.ml, aws.mobile
• Сеть и безопасность: aws.network, aws.security
• Другие: aws.blockchain, aws.enduser, aws.engagement, aws.game, aws.general, aws.iot, aws.media, aws.migration, aws.quantum, aws.robotics, aws. спутник

Далее мы представим одну из этих категорий для визуализации доступных узлов в aws.database.

from diagrams import Diagram
from IPython.display import Image
import diagrams.aws.database as aws_database


database_components = []
for item in dir(aws_database):
    if item[0] != '_':
        if not any(comp.startswith(item) or item.startswith(comp) for comp in database_components):
            database_components.append(item)


with Diagram("AWS Database", show=False, filename="aws_database"):
    mid_index = len(database_components) // 2
    first_line = database_components[:mid_index]
    second_line = database_components[mid_index:]


    prev_node = None
    for item_database in first_line:
        current_node = eval(f"aws_database.{item_database}(item_database)")
        if prev_node is not None:
            prev_node >> current_node
        prev_node = current_node


    prev_node = None
    for item_database in second_line:
        current_node = eval(f"aws_database.{item_database}(item_database)")
        if prev_node is not None:
            prev_node >> current_node
        prev_node = current_node

Image("aws_database.png")

☁️ Вариант использования

Теперь давайте создадим простой план, соответствующий импорту набора данных и обучению модели машинного обучения на AWS.

from diagrams import Diagram, Cluster
from diagrams.aws.storage import S3
from diagrams.aws.analytics import Glue, Athena
import diagrams.aws.ml as ml
from diagrams.aws.integration import StepFunctions
from diagrams.aws.compute import Lambda
from diagrams.aws.network import APIGateway
from IPython.display import Image

with Diagram("AWS Data Processing Pipeline", show=False):

    lambda_raw = Lambda('Get Raw Data')
    # Buckets de S3
    with Cluster("Data Lake"):
        s3_rawData = S3("raw_data")
        s3_stage = S3("staging_data")
        s3_data_capture = S3("data_capture")


    athena = Athena("Athena")
    s3_rawData >> athena
    s3_stage >> athena
    s3_data_capture >> athena

    #  Step Functions Pipeline
    with Cluster("Data Processing Pipeline"):
        step_functions = StepFunctions("Pipeline")

        # Glue Jobs in Step Functions
        with Cluster("Glue Jobs"):
            data_quality = Glue("job_data_quality")
            transform = Glue("job_data_transform")
            dataset_preparation = Glue("job_dataset_model")

        # Define Step Functions Flows
        step_functions >> data_quality >> transform >> dataset_preparation
        s3_rawData >> data_quality

    # SageMaker for model training and deployment
    with Cluster("SageMaker Model Deployment"):
        train_model = ml.SagemakerTrainingJob("job_train_model")
        eval_model = ml.SagemakerGroundTruth("job_evaluate_model")
        endpoint = ml.SagemakerModel("model_enpoint")

    # API Gateway and Lambda for the endpoint
    api_gateway = APIGateway("API_gateway")
    lambda_fn = Lambda("invoke_endpoint")

    # Connection
    lambda_raw >> s3_rawData
    s3_stage >> train_model >> eval_model >> endpoint
    endpoint >> lambda_fn >> api_gateway
    endpoint >> s3_data_capture
    dataset_preparation >> train_model


Image("aws_data_processing_pipeline.png")

Репозиторий

Ниже приведены ссылки на весь код. Если он окажется для вас полезным, вы можете поставить звездочку ⭐️ и подписаться на меня, чтобы получать уведомления о новых статьях. Это поможет мне расти в технологическом сообществе и создавать больше контента.

Если вы хотите узнать, как реализовать сайт документации с использованием этого конвейера, вы можете прочитать статью, которую я опубликовал по следующей ссылке

? Ссылки

1. Диаграммы: https://diagrams.mingrammer.com/