گروه بندی پارامترهای توابع با کمک sphinx

برای گروه‌بندی پارامترهای تابع در مستندسازی با Sphinx به زبان فارسی، ابتدا باید با مفهوم گروه‌بندی پارامترها و استفاده از الگوی استاندارد مستندسازی در Sphinx آشنا شویم. این ابزار به طور گسترده برای مستندسازی پروژه‌های برنامه‌نویسی، به‌ویژه در زبان Python، استفاده می‌شود. تا پایان این آموزش با رادیب همراه باشید. 

در Sphinx از قالب reStructuredText (rst.) و افزونه‌هایی نظیر autodoc برای تولید خودکار مستندات از کد منبع بهره می‌بریم. یکی از امکانات مهم این قالب، توضیح دقیق و ساختارمند پارامترها، مقادیر بازگشتی و استثناهای تابع است.

۱. ساختار پایه مستندسازی پارامترها در 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

    **پارامترهای لاگینگ:**
    :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 برای سهولت مستندسازی استفاده کنید.