مستندسازی ساختمان¶
قبل از انجام هرگونه تغییری در مستندات BeeWare، مفید است که تأیید کنید میتوانید مستندات موجود را بسازید.
قبل از اینکه مستندات را بسازید و یک محیط توسعه را راهاندازی کنید.
شما باید یک تفسیرگر Python 3.13 را نصب و در مسیر خود در
دسترس داشته باشید (یعنی python3.13 باید یک تفسیرگر Python
3.13 را راهاندازی کند).
BeeWare از tox برای تولید مستندات استفاده میکند. دستورات زیر باید
از همان محل فایل tox اجرا شوند که در دایرکتوری ریشه پروژه قرار دارد.
پیشنمایش مستندات زنده¶
برای پشتیبانی از ویرایش سریع مستندات، BeeWare دارای حالت «پیشنمایش زنده» است.
پیشنمایش زنده با هشدارها ساخته خواهد شد!
سرویس زنده برای تکرار و بهبود بهروزرسانیهای مستندات شما در دسترس است. در حالی
که در حال بهروزرسانی موارد هستید، ممکن است یک مشکل نشانهگذاری ایجاد شود.
مشکلاتی که بهعنوان WARNING در نظر گرفته میشوند، باعث شکست ساخت استاندارد
میشوند، اما سرویس زنده طوری تنظیم شده است که در خروجی کنسول هشدارها را نمایش
دهد و در عین حال ساخت را ادامه دهد. این امکان را به شما میدهد که بدون نیاز به
راهاندازی مجدد پیشنمایش زنده، فرآیند تکرار را انجام دهید.
یک WARNING با یک ERROR متفاوت است. اگر مسئلهای را معرفی کنید که بهعنوان یک
ERROR در نظر گرفته شود، سرویس زنده شکست خواهد خورد و نیاز به راهاندازی مجدد
دارد. تا زمانی که مسئله WARNING حل نشود، دوباره راهاندازی نخواهد شد.
برای راهاندازی سرور زنده:
(venv) $ tox -e docs-live
(venv) $ tox -e docs-live
(venv) C:\...>tox -e docs-live
این کار مستندات را ایجاد میکند، یک سرور وب راهاندازی میکند تا مستندات را ارائه دهد و سیستم فایل را برای هرگونه تغییر در منبع مستندات زیر نظر میگیرد.
پس از راهاندازی سرور، چیزی شبیه به موارد زیر را در خروجی کنسول مشاهده خواهید کرد:
INFO - [11:18:51] Serving on http://127.0.0.1:8000/
یک مرورگر باز کنید و به آدرس URL ارائهشده بروید. اکنون میتوانید روی مستندات تکرار کنید. اگر تغییری شناسایی شود، مستندات بازسازی خواهد شد و هر مرورگری که صفحهٔ تغییرشده را مشاهده میکند، بهطور خودکار تازهسازی خواهد شد.
docs-live یک گام اولیه است.
اجرای docs-live برای کار با سرور زنده جهت تکرارهای اولیه در نظر گرفته شده است.
شما باید همیشه قبل از ارسال درخواست کش یک ساخت محلی اجرا کنید.
ساخت محلی¶
وقتی تکرارها را به پایان رساندید، باید مستندات را بهصورت محلی بسازید. این فرایند ساخت طوری طراحی شده که در صورت وجود هرگونه مشکل در نشانهگذاری با خطا مواجه شود. این کار به شما امکان میدهد هر چیزی را که ممکن است در سرور زنده از قلم افتاده باشد، شناسایی کنید.
ایجاد یک بیلد محلی¶
برای ایجاد یک ساخت محلی:
(venv) $ tox -e docs
(venv) $ tox -e docs
(venv) C:\...>tox -e docs
خروجی این ساخت در دایرکتوری _build در ریشه پروژه قرار خواهد گرفت.
تولید یک بیلد محلی ترجمهشده¶
مستندات BeeWare به چندین زبان ترجمه شده است. بهروزرسانیهای مستندات انگلیسی ممکن است در نسخههای زبانهای دیگر مشکل ایجاد کند. مهم است که قبل از ارسال درخواست کش، از کارکرد همه نسخهها اطمینان حاصل کنید.
برای تولید یک نسخه از تمام ترجمههای موجود:
(venv) $ tox -e docs-all
(venv) $ tox -e docs-all
(venv) C:\...>tox -e docs-all
خروجی هر کامپایل زبان در دایرکتوری مربوطه با نام _build/html/<languagecode>
قرار میگیرد، که <languagecode> کد دو یا پنجنقطهای زبان موردنظر است (مثلاً
برای فرانسوی fr، برای ایتالیایی it و غیره).
اگر در یک ساخت مشکل پیدا کنید، میتوانید آن ساخت را بهطور جداگانه با اجرای tox
-e docs-<languagecode> اجرا کنید. برای مثال، برای ساخت تنها مستندات فرانسوی،
اجرا کنید:
(venv) $ tox -e docs-fr
(venv) $ tox -e docs-fr
(venv) C:\...>tox -e docs-fr
خروجی یک ساخت تکزبانه در دایرکتوری _build خواهد بود.
لینتگذاری مستندات¶
فرآیند ساخت مشکلات مارکداون را شناسایی میکند، اما BeeWare بررسیهای اضافی بیشتری برای سبک و قالببندی انجام میدهد که به آن «لینتینگ» گفته میشود. برای اجرای بررسیهای لینت:
(venv) $ tox -e docs-lint
(venv) $ tox -e docs-lint
(venv) C:\...>tox -e docs-lint
این تأیید میکند که مستندات حاوی موارد زیر نیست:
- لینکهای مرده
- کلمات اشتباه املایی
اگر املای صحیح یک کلمه بهعنوان اشتباه شناسایی شود، آن کلمه را در لیست داخل
docs/spelling_wordlist اضافه کنید. این کار کلمه را به فرهنگ لغت SpellChecker
اضافه میکند. هنگام افزودن به این لیست، به خاطر داشته باشید:
- ما املای آمریکایی را ترجیح میدهیم، با برخی آزادیها برای اصطلاحات محاورهای خاص برنامهنویسی (مثلاً «apps») و فعلانگاری اسامی (مثلاً «scrollable»).
- هر ارجاع به نام یک محصول باید از شیوهٔ نگارش بزرگنویسی ترجیحی آن محصول استفاده کند. (مثلاً «macOS»، «GTK»، «pytest»، «Pygame»، «PyScript»)
- اگر یک واژه بهعنوان «کد» استفاده میشود، باید بهصورت یک عبارت بستی (
like this) نقل شود، نه اینکه به فرهنگ لغت اضافه شود.
پس از اینکه با موفقیت مستندات را ساختید، آمادهاید تا مستندات را بنویسید.