رشته اسناد پایتون

همانطور که قبلاً در مقاله قبلی با عنوان Commenting Code Python اشاره شد، آموخته اید که مستندسازی یک مرحله ضروری و پیوسته در process توسعه نرم افزار مقاله ذکر شده در بالا به طور خلاصه به معرفی مفهوم رشته های مستند که راهی برای ایجاد مستندات برای کد پایتون از داخل کد است. این مستندات درون کد برای ماژول‌ها، کلاس‌ها، متدها و توابع کار می‌کند و بهترین راه برای مستندسازی تمام کدهای پایتون است.

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

غواصی در Docstrings

عبارت رشته مستندسازی مخفف است رشته مستنداتو کد منبع شما را توصیف می کند – یعنی عملکرد، ماژول یا کلاس شما چه می کند. به عنوان یک نظر معمولی درست زیر سر یک تابع، ماژول، کلاس یا متد اضافه می شود.

یک مثال معمولی به صورت زیر است و از یک کلاس پایتون برای کار با یک دستگاه اندازه گیری مانند سنسور موبایل برای اندازه گیری دما، رطوبت و سرعت باد گرفته شده است.

فهرست 1: کد پایتون با یک رشته سند تک خطی

class Device:
    def __init__(self, temp=0.0):
        "Initialize the Device object with the given temperature value."
        
        self.set_temperature(temp)
        return

برای نوشتن صحیح یک Docstring از تعدادی قرارداد پیروی کنید. این قراردادها با جزئیات بیشتری در این مقاله توضیح داده شده است PEP 257که مخفف عبارت Python Enhancement Proposal است.

رشته اسناد تک خطی

به دلیل سادگی، رشته docstring در لیست 1 به صورت یک نظر تک خطی می آید. به خاطر داشته باشید که متن یک docstring را با حرف بزرگ شروع کنید و آن را با نقطه پایان دهید. مستقر روی با توجه به این واقعیت که کد معمولاً بیشتر از آنچه نوشته شده خوانده می شود، توصیه می شود به جای روش انجام آن، آنچه را که ساختار مستند به عنوان نوعی دستور انجام می دهد، توصیف کنید. ذکر نوع مقداری که به تماس گیرنده برگردانده می شود به درک نتیجه تابع یا روش کمک می کند.

ممکن است متوجه شده باشید که مستندسازی روش از لیست 1 در دو گیومه تک قاب شده است. خوب، تا زمانی که هر دو نقل قول شروع و پایان شبیه به هم باشند، پایتون کاملاً قابل تحمل است و شما همچنین مجاز به استفاده از سه نقل قول تکی و همچنین سه نقل قول دوگانه هستید:

    def get_temperature(self):
        '''Return the stored temperature value as a float value.'''

        return self.temperature
    
    def set_temperature(self, temp):
        """Set the temperature value."""

        self.temperature = float(temp)
        return

لطفاً مطمئن شوید که مظنه‌های پایانی مطابق با قیمت‌های ابتدایی هستند. همچنین، هیچ خط خالی قبل یا بعد از متن docstring اضافه نکنید.

Docstrings چند خطی

علاوه بر این، یک docstring نیز می تواند به عنوان یک نظر چند خطی نوشته شود. هنگام استفاده از نظرات چند خطی، دو چیز تغییر می کند – کپسوله کردن رشته مستند باید در سه گیومه تک یا دوگانه نوشته شود، و ساختار docstring خود معنای عمیق تری دارد که به کل متن اختصاص داده می شود.

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

فهرست 2: رشته اسناد چند خطی

def set_temperature(self, temp):
    """Set the temperature value.

    The value of the temp parameter is stored as a value in
    the class variable temperature. The given value is converted
    into a float value if not yet done.
    """

    self.temperature = float(temp)
    return

پیروی از ساختار docstring برای رشته های چند خطی به شدت توصیه می شود زیرا ابزارهای نمایه سازی خودکار این متون را ارزیابی می کنند و بنابراین متکی هستند روی انطباق با دستور بلوک

فرمت های Docstring

ممکن است انتظار داشته باشید که فقط یک فرمت مدارک الزام آور وجود داشته باشد. متأسفانه بیش از یک مورد وجود دارد و همه این فرمت‌ها با رشته‌های اسناد چند خطی کار می‌کنند.

• متن بازسازی شده (باقی مانده) / ابوالهول: این استاندارد اسناد رسمی پایتون است. از نحو زبان نشانه گذاری سبک وزن متن بازسازی شده (reST) استفاده می کند که از نظر استفاده مشابه Markdown است.
• Google Docstrings: سبک Docstring گوگل
• NumPy/SciPy Docstrings: ترکیبی از متن بازسازی شده (reST) و Google Docstrings. قابل استفاده توسط Sphinx نیز، و کاملاً پرمخاطب.

لیست 3 روش نوشتن docstring با استفاده از reST را نشان می دهد. کلمات کلیدی که می توانید استفاده کنید به شرح زیر است:

• param و type: پارامتر و نوع متغیر آن
• return و rtype: هم مقدار برگشتی و هم نوع تابع یا متد را مشخص کنید
• .. seealso::: بیشتر خواندن
• .. notes::: یک یادداشت اضافه کنید
• .. warning::: یک هشدار اضافه کنید

ترتیب ورودی‌ها ثابت نیست، اما در کل پروژه خود به همان ترتیب پایبند باشید. ورودی ها برای seealso، notes، و warning اختیاری هستند.

فهرست 3: رشته مستند چند خطی با داده های reST

def set_temperature(self, temp):
    """Set the temperature value.

    The value of the temp parameter is stored as a value in
    the class variable temperature. The given value is converted
    into a float value if not yet done.

    :param temp: the temperature value
    :type temp: float
    :return: no value
    :rtype: none
    """

    self.temperature = float(temp)
    return

برای درک رشته‌های اسناد Google، ممکن است نگاهی به آن بیندازید لیست 4. فرمت چگالی کمتری دارد و از فضای افقی بیشتری استفاده می کند.

فهرست 4: رشته اسناد چند خطی (فرمت گوگل)

def set_temperature(self, temp):
    """Set the temperature value.

    The value of the temp parameter is stored as a value in
    the class variable temperature. The given value is converted
    into a float value if not yet done.

    Args:
        temp (float): the temperature value

    Returns:
        no value
    """

    self.temperature = float(temp)
    return

سرانجام، لیست 5 همین روش را در فرمت NumPy docstring نشان می دهد. از فضای عمودی بیشتری استفاده می کند و خواندن آن راحت تر از قالب اصلی به نظر می رسد.

فهرست 5: رشته اسناد چند خطی (فرمت NumPy)

def set_temperature(self, temp):
    """Set the temperature value.

    The value of the temp parameter is stored as a value in
    the class variable temperature. The given value is converted
    into a float value if not yet done.

    Parameters
    ----------
    temp : float
        the temperature value

    Returns
    -------
    no value
    """

    self.temperature = float(temp)
    return

دسترسی به Docstrings

در سیستم کمک تعاملی پایتون، رشته مستند از طریق در دسترس است __doc__ صفت. لیست 6 روش استفاده از کد برای دسترسی به رشته مستندات را نشان می دهد که در مثال ما مبتنی بر آن است روی لیست 1.

فهرست 6: دسترسی به مقدار docstring

>>> def set_temperature (self, temp):
...     """Set the temperature value."""
...     temperature = float(temp)
...     return
... 
>>> print(set_temperature.__doc__)
Set the temperature value.

تعدادی ابزار وجود دارد که به طور خودکار مستندات را از رشته‌های مستند تولید می‌کنند، مانند Sphinx، Epydoc، داکسیژن، PyDoc، pdoc، و اتودوک پسوند برای Sphinx. اکثر آنها اسناد HTML را برای استفاده محلی تولید می کنند.

Pydoc بخشی از توزیع پایتون است و اطلاعات مربوط به یک ماژول را برای آن استخراج می کند console، یک مرورگر وب یا به عنوان یک سند HTML. در داخل پوسته پایتون از help() تابع به منظور کسب اطلاعات بیشتر در مورد یک ماژول، تابع، کلاس یا متد. شکل 1 Docstring را نشان می دهد لیست 1 از طریق سیستم کمکی پایتون

شکل 1: رشته مستند استخراج شده

برای مشاهده اسناد داخلی برای همه ماژول های پایتون که به صورت محلی نصب شده اند، می توانید pydoc را به عنوان یک وب سرور محلی اجرا کنید. با استفاده از پارامتر -p به دنبال آن شماره پورت یک وب سرور کوچک راه اندازی می کند که با استفاده از پورت داده شده قابل دسترسی است. لیست 7 سرور pydoc را در پورت 1234 راه اندازی می کند و شکل 2 اطلاعات استخراج شده و در دسترس توسط pydoc را نشان می دهد.

لیست 7: اجرای pydoc به عنوان یک وب سرور

$ pydoc3 -p 1234
Server ready at http://localhost:1234/
Server commands: (b)rowser, (q)uit
server>
...

شکل 2: رشته مستند استخراج شده روی یک وب سرور محلی

نتیجه

پیروی از دستورالعمل‌های مستندسازی به شما و دیگران کمک می‌کند تا کد منبع را امروز و بعداً درک کنید. Docstrings برای بیش از این مورد استفاده می شود، به عنوان مثال برای تولید کتابچه راهنمای کاربر. این ایده در ذهن به پروژه ها در مقیاس بزرگتر اجازه می دهد.