منابع API را برای پروژه های پایتون 🐍 خود ایجاد کنید!

pdoc3 چیست؟

Pdoc3 یک ابزار قدرتمند تولید اسناد است که به طور خاص برای پایتون طراحی شده است. این به طور خودکار اسناد HTML تمیز و قابل خواندن را از رشته های اسناد در کد شما تولید می کند. با pdoc3، می‌توانید بدون زحمت اسنادی با ظاهر حرفه‌ای برای پروژه‌های خود ایجاد کنید و درک و استفاده از کد شما را برای کاربران و همکاران آسان‌تر کنید.

مثال

pdoc3 چگونه کار می کند؟

Pdoc3 یک ماژول پایتون است که فرآیند تولید اسناد از رشته‌های اسناد در کد شما را خودکار می‌کند. برای استخراج اطلاعات از ماژول های پایتون و تولید اسناد HTML تمیز و خوانا، از یک گردش کار ساده و سرراست پیروی می کند.

در اینجا یک مرور مختصر از نحوه عملکرد pdoc3 آورده شده است:

1. تجزیه کد: Pdoc3 با تجزیه کد پایتون شما شروع می شود. ساختار ماژول‌ها و توابع شما را برای استخراج اطلاعات مرتبط مانند رشته‌های اسناد، امضاهای تابع و تعاریف کلاس تجزیه و تحلیل می‌کند.

2. استخراج Docstrings: Docstrings نظرات خاصی هستند که در ابتدای توابع، کلاس ها یا ماژول ها برای ارائه مستندات قرار می گیرند. Pdoc3 این رشته های مستند را شناسایی کرده و آنها را برای پردازش بیشتر استخراج می کند. Docstrings معمولاً حاوی اطلاعاتی در مورد هدف، استفاده و پارامترهای یک تابع یا کلاس است.

3. تولید اسناد HTML: هنگامی که رشته‌های اسناد استخراج می‌شوند، pdoc3 مستندات HTML را بر اساس اطلاعات جمع‌آوری‌شده تولید می‌کند. این یک طرح تمیز و سازماندهی شده ایجاد می کند که شامل سلسله مراتب ماژول، توضیحات عملکرد، جزئیات پارامتر، و هر گونه اطلاعات اضافی ارائه شده در رشته های اسنادی است.

4. گزینه های سفارشی سازی: pdoc3 گزینه‌های سفارشی‌سازی مختلفی را برای تطبیق اسناد با نیازهای شما فراهم می‌کند. می توانید دایرکتوری خروجی را مشخص کنید، موضوع را تغییر دهید و کنترل کنید که کدام ماژول ها در فرآیند تولید اسناد گنجانده شوند. این گزینه ها به شما این امکان را می دهند که سبک مستندسازی را با نیازهای پروژه خود مطابقت دهید.

5. اسناد خدمت: علاوه بر تولید فایل های HTML ایستا، pdoc3 همچنین می تواند اسناد را به عنوان یک وب سرور محلی ارائه کند. این ویژگی به شما امکان می‌دهد در زمان ایجاد تغییرات در کد خود، مستندات را در زمان واقعی مشاهده کنید، و راهی مناسب برای تکرار و به‌روزرسانی مستندات در حین توسعه پروژه خود ارائه می‌دهد.

نصب pdoc3

برای شروع با pdoc3، باید آن را نصب کنید. شما می توانید این کار را به راحتی با استفاده از pip، نصب کننده بسته Python انجام دهید. ترمینال خود را باز کنید و دستور زیر را اجرا کنید:

pip install pdoc3

با استفاده از pdoc3

• از آنجایی که استفاده از آن بسیار آسان است، بنابراین به گفته من بهترین راه برای آزمایش pdoc3 کاوش است، از این رو، از دستور help برای دیدن گزینه های مختلف در دسترس استفاده کنید.

pdoc3 --help

با این حال در اینجا چند مورد استفاده اساسی وجود دارد

pdoc3 project_location --pdf

pdoc3 project_location --html

• برای اسناد در علامت گذاری (مفید با اسفینکس یا mkdocs)

pdoc3 "project location" -o DIR

بررسی وبلاگ های قبلی