از اسناد پروژه خود نهایت استفاده را ببرید—از Sphinx برای ایجاد مستندات جذاب و جامع HTML استفاده کنید.
Sphinx یکی از محبوب ترین ابزار برای تولید اسناد است. در سراسر جامعه پایتون، توسعه دهندگان از این نرم افزار رایگان و منبع باز استفاده می کنند. می‌تواند متن را مستقیماً از کد یا فایل‌های علامت‌گذاری استخراج کند و سپس از آن برای تولید اسناد در قالب‌های مختلف مانند متن ساده، HTML، PDF و EPUB استفاده کند.
راه اندازی Sphinx
قبل از اینکه Sphinx را راه اندازی کنید، به کارهایی که انجام می دهد و برخی از ویژگی های اصلی آن نگاهی بیندازید.
اسفینکس چیست و چه کاربردی دارد؟
همانطور که گفته شد، Sphinx یک تولید کننده اسناد است. به طور پیش‌فرض، از زبان نشانه‌گذاری reStructuredText (RST) استفاده می‌کند، اما از طریق برنامه‌های افزودنی شخص ثالث، می‌تواند از Markdown، زبان نشانه‌گذاری متن ساده محبوب نیز استفاده کند. سپس این فایل های RST یا نشانه گذاری را به HTML، PDF، صفحات دستی یا فرمت های دیگری که ترجیح می دهید تبدیل می کند.
برخی از ویژگی های Sphinx عبارتند از:
- امکان تولید مستندات از روی کد.
- امکان ارجاع متقابل صفحات اسناد مختلف با استفاده از پیوندهای خودکار برای توابع، کلاس ها، نقل قول ها و اصطلاحات واژه نامه.
- برجسته سازی نحو برای بلوک های کد.
- پشتیبانی از تم هایی که می توانند ظاهر و احساس اسناد را تغییر دهند.
- تعریف آسان درخت سند از طریق فهرست مطالب.
- امکان ادغام با افزونه های شخص ثالث برای افزودن قابلیت های بیشتر به اسناد مانند تست قطعه کد.
نصب Sphinx
قبل از نصب Sphinx، مطمئن شوید که پایتون 3 را در محیط توسعه خود نصب کرده اید. سپس می توانید با اجرای دستور زیر در ترمینال خود از مدیر بسته pip برای نصب Sphinx استفاده کنید:
pip install sphinx
با این کار Sphinx و وابستگی های آن دانلود و نصب می شود.
پس از نصب، دستور زیر را در خط فرمان اجرا کنید.
sphinx-build --version
اگر همه چیز خوب کار کرد، باید شماره نسخه بسته Sphinx را که به تازگی نصب کرده اید ببینید.
ایجاد یک پروژه ابوالهول جدید
هنگامی که Sphinx را نصب کردید، به دایرکتوری کاری خود بروید و دستور sphinx-quickstart را برای ایجاد یک پروژه Sphinx جدید اجرا کنید.
sphinx-quickstart
این دستور از شما می خواهد که به یک سری سوالات در مورد نحوه پیکربندی پروژه Sphinx خود پاسخ دهید. می توانید نام پروژه را مشخص کنید و از گزینه های پیش فرض برای سوالات دیگر استفاده کنید. در آینده، ممکن است بخواهید پاسخ ها را بر اساس پروژه خود سفارشی کنید.
اگر محتویات دایرکتوری خود را لیست کنید، خواهید دید که این دستور چند فایل را برای شما ایجاد می کند. conf.py حاوی مقادیر پیکربندی است و index.rst به عنوان صفحه خوش آمدگویی مستندات شما عمل می کند. دایرکتوری ساخت میزبان مستندات تولید شده خواهد بود و Sphinx از یک Makefile (make.bat در ویندوز) برای ساخت اسناد استفاده می کند.
نوشتن مستندات با استفاده از ابوالهول
فایل index.rst در ریشه دایرکتوری شما صفحه اصلی برنامه شما است. بنابراین، آن را با یک ویرایشگر متن مانند VS Code – یا هر ویرایشگر کد خوب و رایگان دیگری – برای ویرایش آن باز کنید.
شما می توانید index.rst را به دلخواه تغییر دهید، اما یک چیزی که حداقل باید داشته باشد، دستورالعمل root toctree (درخت فهرست مطالب) است. این امر ضروری است زیرا چندین فایل را به یک سلسله مراتب اسناد متصل می کند.
برای افزودن مستندات به فایل index.rst، می توانید از نشانه گذاری RST استفاده کنید.
به عنوان مثال، یک فایل index.rst برای ماژول math_utils در نظر بگیرید. این فایل ممکن است شامل نمای کلی مختصری از هدف ماژول و فهرست مطالبی باشد که به صفحات دیگر مستندات پیوند دارد.
Welcome to Math Utils
======================
.. toctree::
:maxdepth: 2
Getting Started
---------------
To use this module, you'll need the following:
* Python installed.
* A text editor
Math Utils
----------
The `math-utils` module provides basic math functions like addition and
subtraction.
در صورت نیاز می توانید فایل های .rst بیشتری اضافه کنید. به عنوان مثال، می توانید یک راهنمای مشارکت در فایلی به نام contributing.rst ایجاد کنید که حاوی دستورالعمل های مشارکت زیر است.
Contributing Guide
==================
We welcome contributions to our project! Here are some guidelines for
contributing:
- Fork the project on GitHub.
- Make your changes on a new branch.
- Write tests to ensure that your changes work correctly.
- Submit a pull request with your changes.
- Make any requested changes.
Thank you for contributing!
سپس می توانید این فایل را از index.rst با افزودن یک بخش جدید به دستورالعمل toctree پیوند دهید:
.. toctree::
:maxdepth: 2
:caption: Table of Contents
contributing
این یک مورد جدید به نام مشارکت در فهرست مطالب ایجاد می کند که با کلیک کاربر را به صفحه مشارکت می برد.
هنگامی که اسناد را نوشتید، مرحله بعدی ساخت آن است. در اینجا، ساختن مستندات به معنای تولید صفحات HTML، دستی یا PDF از فایل‌های RST است.
ساخت مستندات
برای ساخت مستندات با استفاده از Sphinx، باید دستور make html را در ریشه پوشه خود که در آن makefile قرار دارد اجرا کنید.
make html
شما باید فایل های HTML را در پوشه build ببینید. اگر در حین ساخت خطاهایی وجود داشت، Sphinx در ترمینال به شما اطلاع می دهد.
برای مشاهده مستندات، فایل index.html را در مرورگر خود باز کنید:
شما باید بتوانید از فهرست مطالب به راهنمای کمک کننده بروید.
سفارشی سازی مستندات
در حال حاضر، مستندات دارای یک سبک اولیه است. اگر می‌خواهید آن را سفارشی کنید، شاید با افزودن رنگ‌های نام تجاری خود یا حتی اضافه کردن حالت تاریک، می‌توانید تم‌های داخلی دیگر را نصب و استفاده کنید یا تم سفارشی خود را ایجاد کنید.
برای نشان دادن، سعی کنید موضوع را به موضوعی به نام طبیعت تغییر دهید:
- فایل پیکربندی Sphinx conf.py را در فهرست پروژه Sphinx خود باز کنید.
- به دنبال خطی باشید که گزینه html_theme را تعریف می کند و آن را به طبیعت تغییر دهید
- فایل پیکربندی را ذخیره کنید و اسناد را دوباره بسازید تا تغییرات خود را ببینید.
صفحه اصلی اسناد باید به این شکل باشد.
اگر نمی‌خواهید از تم‌های داخلی استفاده کنید، همیشه می‌توانید از یک تم Sphinx شخص ثالث استفاده کنید.
مستندسازی کد خود با استفاده از Docstrings
Sphinx اسناد پایتون شما را از متنی که در فایل های RST می نویسید تولید می کند. در حالی که این در برخی موارد کافی است، ممکن است بخواهید از رشته‌های اسناد در کد خود برای آن در سطح ماژول نیز استفاده کنید.
رشته‌های اسناد مستقیماً در فایل‌های منبع پروژه شما زندگی می‌کنند. آنها به شما اجازه می دهند آنچه را که کد انجام می دهد توصیف کنید، مثال هایی ارائه دهید و حتی برای آن نمونه ها تست هایی ایجاد کنید. هنگامی که رشته‌های اسنادی را نوشتید، می‌توانید با استفاده از Sphinx اسنادی را از آنها ایجاد کنید.