في هذه المقالة، سأرشدك خطوة بخطوة لإنشاء وثائق مرئية ديناميكية وتفاعلية باستخدام أدوات Diagram-as-Code. بدلاً من الصور الثابتة، سنقوم بإنشاء الرسوم البيانية برمجيًا، مما يضمن تحديثها دائمًا وسهولة صيانتها.

؟ الرسم البياني كرمز

المخطط كرمز هو أسلوب يسمح لك بإنشاء رسوم بيانية من خلال التعليمات البرمجية بدلاً من أدوات الرسوم التقليدية. بدلاً من إنشاء الرسوم التخطيطية يدويًا، يمكنك كتابة تعليمات برمجية في ملف نصي لتحديد بنية الرسوم التخطيطية ومكوناتها واتصالاتها.

تتم بعد ذلك ترجمة هذا الرمز إلى صور رسومية، مما يسهل التكامل والتوثيق في مشاريع البرامج، حيث يكون مفيدًا بشكل خاص لإنشاء وتحديث المخططات المعمارية والتدفقية برمجيًا.

ما هي المخططات؟

المخططات هي مكتبة بايثون التي تطبق نهج المخطط كرمز، مما يتيح لك إنشاء مخططات البنية التحتية المعمارية وأنواع أخرى من المخططات من خلال التعليمات البرمجية. باستخدام المخططات، يمكنك بسهولة تحديد مكونات البنية التحتية السحابية (مثل 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 (خدمات ويب أمازون)

يمكننا استخدام عقد أمازون، والتي يتم تنظيمها في عدة فئات، مثل:

• التحليلات والأعمال: 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.

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/