pydoc --- تولیدگر مستندات و سامانهی راهنمای برخط¶
کد منبع: Lib/pydoc.py
ماژول pydoc بهطور خودکار مستندات را از ماژولهای پایتون تولید میکند. این مستندات میتواند بهصورت صفحاتی از متن در کنسول نمایش داده شود، به یک مرورگر وب ارائه شود، یا در پروندههای HTML ذخیره شود.
برای ماژولها، کلاسها، توابع و متدها، مستندات نمایشدادهشده از رشته مستند آن شیء (یعنی ویژگی __doc__) و بهصورت بازگشتی از اعضای قابل مستندسازی آن گرفته میشود. اگر رشته مستندی وجود نداشته باشد، pydoc تلاش میکند توضیحی را از بلوکی از سطرهای کامنت درست بالای تعریف کلاس، تابع یا متد در پرونده منبع، یا در ابتدای ماژول به دست آورد (به inspect.getcomments() مراجعه کنید).
تابع توکار help() سامانهی راهنمای برخط را در مفسر تعاملی فراخوانی میکند، که از pydoc برای تولید مستندات آن بهصورت متن روی کنسول استفاده میکند. همان مستندات متنی را میتوان از بیرون مفسر پایتون نیز، با اجرای pydoc بهعنوان یک اسکریپت در خط فرمان سیستمعامل مشاهده کرد. برای مثال، اجرای
python -m pydoc sys
در اعلان پوسته، مستندات ماژول sys را به سبکی مشابه صفحههای راهنمای دستور man در یونیکس نمایش میدهد. آرگومان pydoc میتواند نام یک تابع، ماژول یا بسته، یا یک ارجاع نقطهدار به یک کلاس، متد یا تابع درون یک ماژول یا ماژولی در یک بسته باشد. اگر آرگومان pydoc شبیه به یک مسیر باشد (یعنی شامل جداکنندهی مسیر برای سیستمعامل شما باشد، مانند اسلش در یونیکس) و به یک پرونده منبع پایتون موجود ارجاع دهد، مستندات برای آن پرونده تولید میشود.
توجه
برای یافتن اشیاء و مستندات آنها، pydoc ماژول(های) مورد مستندسازی را ایمپورت میکند. بنابراین، هر کدی در سطح ماژول در آن هنگام اجرا خواهد شد. از یک نگهبان if __name__ == '__main__': استفاده کنید تا کد فقط زمانی اجرا شود که یک پرونده بهعنوان یک اسکریپت فراخوانی میشود، نه اینکه صرفاً ایمپورت میشود.
هنگام چاپ خروجی در کنسول، pydoc تلاش میکند خروجی را برای خواندن آسانتر صفحهبندی کند. اگر یکی از متغیرهای محیطی MANPAGER یا PAGER تنظیم شده باشد، pydoc از مقدار آن بهعنوان یک برنامه صفحهبندی استفاده خواهد کرد. وقتی هر دو تنظیم شده باشند، از MANPAGER استفاده میشود.
تعیین پرچم -w پیش از آرگومان باعث میشود مستندات HTML بهجای نمایش متن در کنسول، در پروندهای در پوشه جاری نوشته شود.
با مشخص کردن پرچم -k پیش از آرگومان، در سطرهای خلاصهی همهی ماژولهای موجود به دنبال کلیدواژهی دادهشده بهعنوان آرگومان جستجو میشود؛ باز هم به شیوهای مشابه فرمان man در یونیکس. خط خلاصهی یک ماژول، اولین خط از رشتهی مستندات آن است.
همچنین میتوانید از pydoc برای راهاندازی یک سرور HTTP روی ماشین محلی استفاده کنید که مستندات را به مرورگرهای وب مراجعهکننده ارائه میدهد. python -m pydoc -p 1234 یک سرور HTTP را روی پورت ۱۲۳۴ راهاندازی میکند و به شما امکان میدهد مستندات را در http://localhost:1234/ در مرورگر وب دلخواه خود مرور کنید. با مشخص کردن 0 بهعنوان شمارهی پورت، یک پورت استفادهنشده دلخواه انتخاب میشود.
هشدار
سرور HTTP ماژول pydoc برای استفادهی محلی در حین توسعه در نظر گرفته شده است و برای استفاده در محیط عملیاتی مناسب نیست.
python -m pydoc -n <hostname> سروری را راهاندازی میکند که در نام میزبان دادهشده گوش میدهد. بهطور پیشفرض، نام میزبان 'localhost' است، اما اگر میخواهید سرور از ماشینهای دیگر قابلدسترسی باشد، ممکن است بخواهید نام میزبانی را که سرور به آن پاسخ میدهد تغییر دهید. در طول توسعه، این کار بهویژه زمانی مفید است که بخواهید pydoc را از داخل یک کانتینر اجرا کنید.
python -m pydoc -b سرور را راهاندازی میکند و همچنین یک مرورگر وب را به صفحهی اندیس ماژولها باز میکند. هر صفحهی ارائهشده یک نوار پیمایش در بالا دارد که در آن میتوانید دربارهی یک آیتم منفرد راهنمایی دریافت کنید، همهی ماژولها را با کلیدواژهای در خط خلاصهی آنها جستجو کنید و به صفحههای اندیس ماژولها، موضوعات و کلیدواژهها بروید.
هنگامی که pydoc مستندات را تولید میکند، از محیط و مسیر جاری برای مکانیابی ماژولها استفاده میکند. بنابراین، اجرای pydoc spam دقیقاً همان نسخه از ماژول را مستند میکند که اگر مفسر پایتون را اجرا کنید و import spam را تایپ کنید، به دست میآورید.
فرض میشود مستندات ماژولهای اصلی در https://docs.python.org/X.Y/library/ قرار داشته باشند، که X و Y شمارههای نسخه اصلی و فرعی مفسر پایتون هستند. میتوان این مورد را با تنظیم متغیر محیطی PYTHONDOCS روی یک URL متفاوت یا یک پوشه محلی حاوی صفحات راهنمای مرجع کتابخانه تغییر داد.
تغییر یافته در نسخهی 3.2: گزینه -b اضافه شد.
تغییر یافته در نسخهی 3.3: گزینهی خط فرمان -g حذف شد.
تغییر یافته در نسخهی 3.4: pydoc اکنون برای استخراج اطلاعات امضای فراخوانپذیرها از inspect.signature() بهجای inspect.getfullargspec() استفاده میکند.
تغییر یافته در نسخهی 3.7: گزینه -n افزوده شد.