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

نوشتن DocString فرمتهای مختلفی دارد که ما فرمت Google را به دلیل سادگی ترجیح دادیم.

برای اینکه داخل کد توضیحاتی بنویسید و بعد بتوانید هم توضیحات را به شکل فایلهای HTML استخراج کنید روشهای مختلفی وجود دارد. ما از mkDocs و mkDocStrings استفاده کردیم.

در سایت realPython مقاله خوبی هست که تقریبا همه چیز را توضیح داده. من قسمتهای مهم آن را اینجا می آورم.

اول باید ابزارهای مورد نیاز را نصب کنید:

PS> python -m venv venv
PS> venv\Scripts\activate
(venv) PS> python -m pip install mkdocs
(venv) PS> python -m pip install "mkdocstrings[python]"
(venv) PS> python -m pip install mkdocs-material

 

بعد یک پوشه جدید و فایل YML برای داکیومنتها درست می کنید:

(venv) $ mkdocs new .

 

به عنوان مثال در فایل mkdocs.yml می توانید اینها را بنویسید:

site_name: ERP
dev_addr: '127.0.0.1:8001'

theme:
  name: "material"
  language: 'fa'
  direction: 'rtl'

plugins:
  - search
  - autorefs
  - mkdocstrings

nav:
  - Index: index.md
  - reference.md

اگر ساختار فایلها در پروژه شما مانند این تصویر باشد:

 

آنگاه برای اینکه docstring ها را استخراج کنید باید مثلا در فایل reference.md چنین بنویسید:

::: src.apps.hrms.models.attendance
::: src.apps.hrms.models.base 

حالا با دستور زیر می توانید فایلهای HTML را استخراج کنید:

(venv) $ mkdocs serve

یا با این دستور یک پوشه به اسم site حاوی html ها ایجاد کنید:

(venv) $ mkdocs build

 

حالا توضیحاتی در مورد نحوه نوشتن DocStrings:

فرمت google برای نوشتن docString را ببینید.

 

اگر CustomUser یک کلاس شما باشد و  یک Attribute به نام user از نوع آن تعریف کرده باشید برای docstring باید اینطور بنویسید:

        user (CustomUser): کارمند

دقت کنید که بین user و ) دقیقا یک فضای خالی ، بین : و ( هیچ فضای خالی و بین : و متن توضیحی یک فضای خالی قرار دارد. تغییر دادن این ترتیب باعث به همریختن خروجی HTML می شود.

همین طور دقت کنید که mkdocs نیازی به نام پکیج حاوِی کلاس CustomUser ندارد و بلکه اگر آن را بزنید دیگر نمی تواند لینک به داکیومنت مربوط به آن ایجاد کند.

در مورد Choiceها هم فقط نام کلاس را بنویسید. مثلا اگر کلاسی به این شکل دارید:

class Gender(models.IntegerChoices):
    """جنسیت.
    Attributes:
        MALE : مرد
        FEMALE : زن
    """
    MALE = 1, _("مرد")
    FEMALE = 2, _("زن")

 

و یک Attribute از این نوع دارید باید بنویسید:

gender (Gender): جنسیت 

با این کار این سطر به داکیومنت Gender لینک می شود.

اگر بخواهید docString شما مستقلا و بدون رجوع به کد قابل استفاده باشد باید برای همه مقادیر Choice ها هم توضیحی بنویسید.

 

وقتی یک تابع فقط یک مقدار برگشتی داشته باشد از آنجا که این مقدار برگشتی نام ندارد اینطور بنویسید:

        Returns:
            (UserDepartment):  دپارتمان