مستندسازی کدها در پایتون

برای اینکه کدهای ما برای افراد دیگر و همچنین خودمان در زمانهای آتی قابل استفاده باشد، مستندسازی آنها هنگام نوشتن امری ضروری می باشد. برای مستندسازی انواع فرمهای استانداردی وجود دارد که در این نوشته به یکی از آنها که سازگار با محیط Spyder است، پرداخته خواهد شد.

بسم الله الرحمن الرحیم

احتمالا موقع برنامه‌نویسی به زبان پایتون و استفاده از Spyder با توضیحاتی که برای توابع و کلاسها ظاهر می شود، روبرو شده اید. این توضیحات برای کاربر بسیار راهگشا هستند و موجب عدم نیاز به مراجعه مجدد به مراجع مرتبط با کتابخانه می شود. احتمالا برایتان این سوال پیش آمده است که چگونه می‌توانید برای کدهای خودتان و توابعی که می نویسید، چنین امکانی فراهم نمایید. در این نوشته به نحوه انجام این کار پرداخته می شود.

اصولا برای نوشتن مستندات یک کلاس یا تابع در سطر بعد از تعریف اولیه کلاس یا تابع با گذاشتن سه کوتیشن (یا سه دابل کوتیشن) شروع محدوده متنی برای نوشتن اعلان می گردد. برای نشان دادن اتمام محدوده نیز باز از سه کوتیشن (یا سه دابل کوتیشن) استفاده می شود. در سطر اول بعد از شروع محدوده توضیح کوتاهی برای تابع یا کلاس نوشته می شود و بعد از آن مواردی مثل پارامترهای ورودی، خروجی‌های تابع و مثال برای استفاده نوشته می شوند. توضیح نحوه نوشتن مستندسازی بخش بندی شده متناسب با استاندارد numpy آنگونه که در محیط Spyder نمایش داده می شود با یک مثال آسانتر است لذا قطعه کد زیر را در نظر بگیرید:

def zero_mf(x, params=None):
    """
    All zero membership function.
    
    Parameters
    ----------
    x : 
        numpy (n,) shaped array
        
        The array like input x indicates the points from universe of 
        discourse in which the membership function would be evaluated.
    params : 
        List 
        
        Additional parameters for the membership function, which is not 
        needed for zero memebership function.
    
    Returns
    -------
    ndarray
        Returns a vector of membership values corresponding with the input.
    
    Examples
    --------
    
    >>> x = linspace(0, 1, 201)
    >>> membership_value = zero_mf(x)
    """
    return zeros_like(x)

مستندات تابع فوق در محیط Spyder به شکل زیر نمایش داده می شود:

به قسمت مستندات کدهای نوشته شده دقت نمایید. همانطور که دیده می شود بعد از سطر اول که توضیح کوتاهی در مورد تابع داده شده است، با یک سطر فاصله قسمت Parameters شروع شده است. بعد از کلمه Parameters در سطر بعد با گذاشتن تعدادی خط تیره (برای مشاهده بهتر حتی در حالت متنی بهتر است تعداد خط تیره‌ها با تعداد کاراکترهای سطر بالایی برابر باشد) عبارت Parameters با خط درشتتر و رنگ متفاوت و خط کمرنگی در زیر، مانند یک زیر فصل ایجاد می شود. در ادامه هر یک از متغیرهای ورودی تعریف شده و در سطر بعد پس از یک بار tab زدن به توصیف متغیر ورودی پرداخته شده است. همانطور که مشهود است نوشته و اتمام سطر بدون indentation اضافی، باعث پر رنگ شدن نوشته شده است. توضیحات نیز با یک indentation بیشتر افزوده شده است. بعد از تعریف دو متغیر x و  params قسمت دیگر Returns شروع شده است که در آن خروجی تابع توضیح داده شده است. بعد از آن نیز قسمت مثالها یا Examples  با همان روش نوشتن نام قسمت و خط تیره در سطر پایین ایجاد شده است. برای اینکه متنی که نوشته ایم کد تلقی گردد و رنگ بندی مشابه یک کد انجام گیرد ابتدای سطر سه علامت <<< نوشته می شود که گویی در ترمینال پایتون در حال نوشتن برنامه هستیم …

با این توضیحات ساده و روش آسان می توان مستنداتی استانداردتر و همچنین زیبا ایجاد کرد که قابلیت استفاده کدهای نوشته شده توسط ما را برای دیگران افزایش می دهد. خروجی نمایش داده شده توسط Spyder با استفاده از کتابخانه های پایتونی که برای تبدیل مستندات به فایل html یا pdf طراحی شده اند، ایجاد می گردد که برای مثال از میان آن‌ها می توان به Sphinx اشاره کرد. اگر یک کتابخانه جدید می نویسید استفاده از این امکان برای ایجاد documentation آنلاین باعث تسریع و ساده تر شدن کارهای شما خواهد شد.