تجميع معلمات الوظيفة بمساعدة sphinx

لتجميع معلمات الوظيفة في وثائق Sphinx باللغة الفارسية، يجب علينا أولاً أن نتعرف على مفهوم تجميع المعلمات واستخدام نمط التوثيق القياسي في Sphinx. تُستخدم هذه الأداة على نطاق واسع لتوثيق مشاريع البرمجة، وخاصةً في لغة بايثون. ابقى مع راديب حتى نهاية هذا البرنامج التعليمي.

في Sphinx، نستخدم تنسيق reStructuredText (rst.) والمكونات الإضافية مثل autodoc لإنشاء الوثائق تلقائيًا من الكود المصدر. إحدى الميزات المهمة لهذا القالب هي الشرح التفصيلي والمنظم لمعلمات الوظيفة وقيم الإرجاع والاستثناءات.

١. الهيكل الأساسي لتوثيق معاملات الدوال في Sphinx

لتوثيق الدوال في Sphinx، يمكن استخدام الصيغة التالية:

اشتري سيرفر افتراضي بأفضل جودة وسعر في راديب، انقر هنا

def sample_function(param1: int, param2: str, param3: bool = True) -> str:
    """
    وصف مختصر للدالة

    :param param1: رقم صحيح
    :type param1: int
    :param param2: سلسلة نصية يتم إدخالها إلى الدالة
    :type param2: str
    :param param3: قيمة منطقية افتراضية
    :type param3: bool
    :return: سلسلة نصية كإخراج
    :rtype: str
    """
    return f"{param1} - {param2} - {param3}"

في هذا المثال:

• يتم استخدام :param لوصف كل معلمة.
• يتم استخدام :type لتحديد نوع المعلمة.
• توضح النصوص بعد هذه الوسوم وظيفة كل معلمة.
• يتم استخدام :return: لتوضيح القيمة المرجعة، و:rtype: لتحديد نوعها.

٢. تجميع معاملات الدوال في التوثيق

عندما تحتوي الدوال على عدد كبير من المعاملات، يُفضل تجميع المعاملات ذات الصلة ضمن فئات محددة. يمكن القيام بذلك يدويًا أو باستخدام إضافات معينة.

مثال على التجميع اليدوي:

def configure_server(ip_address: str, port: int, timeout: int, retry: bool, log_level: str):
    """
    إعداد الخادم

    **معاملات الشبكة:**
    :param ip_address: عنوان IP للخادم
    :type ip_address: str
    :param port: منفذ الاتصال
    :type port: int

    **إعدادات الاتصال:**
    :param timeout: مدة المهلة بالثواني
    :type timeout: int
    :param retry: هل يتم إعادة إرسال الطلب أم لا
    :type retry: bool

    **إعدادات التسجيل (logging):**
    :param log_level: مستوى التسجيل (DEBUG, INFO, ERROR)
    :type log_level: str
    """
    pass

في هذا المثال، تم استخدام أوصاف نصية (**عنوان القسم:**) لتجميع المعاملات. هذه الطريقة بسيطة وفعالة.

٣. استخدام وسوم sphinx.ext.napoleon

تتيح الإضافة napoleon في Sphinx توثيقًا بأسلوب Google أو NumPy، مما يوفر دعمًا أفضل لتجميع المعاملات.

مثال باستخدام أسلوب Google:

def database_connection(host: str, port: int, username: str, password: str, use_ssl: bool) -> bool:
    """
    الاتصال بقاعدة البيانات

    Args:
        host (str): عنوان خادم قاعدة البيانات
        port (int): منفذ الاتصال
        username (str): اسم المستخدم
        password (str): كلمة المرور
        use_ssl (bool): هل يتم إنشاء اتصال آمن

    Returns:
        bool: حالة نجاح الاتصال
    """
    return True

٤. تفعيل إضافة napoleon

لتفعيل هذه الإضافة، افتح ملف conf.py في Sphinx وأضف السطر التالي:

extensions = ['sphinx.ext.napoleon']

٥. توليد التوثيق تلقائيًا باستخدام autodoc

إذا كنت ترغب في توليد التوثيق تلقائيًا من الكود، يمكنك تنفيذ الأمر التالي:

sphinx-apidoc -o docs/ your_project/

الاستنتاج

من خلال الجمع بين الطرق اليدوية وإضافة napoleon في Sphinx، يمكنك إنشاء توثيقات دقيقة وقابلة للقراءة ومنظمة للدوال والفئات في مشاريعك. إذا كنت تعمل على مشروع كبير، يُوصى بشدة باستخدام napoleon لتسهيل عملية التوثيق.