وثائق البناء¶
قبل إجراء أي تغييرات على وثائق BeeWare, من المفيد التأكد من أنه يمكنك إنشاء الوثائق الموجودة.
قبل إنشاء الوثائق، قم بإعداد بيئة التطوير.
يجب أن يكون مترجم Python 3.13 مثبتًا ومتاحًا في مسارك
(أي أن python3.13 يجب أن يبدأ مترجم Python 3.13).
BeeWare يستخدم tox لإنشاء الوثائق. يجب تشغيل أوامر tox التالية من
نفس موقع ملف tox.ini، الموجود في الدليل الجذر للمشروع.
معاينة التوثيق المباشر¶
لدعم التحرير السريع للوثائق، يحتوي BeeWare على وضع "المعاينة المباشرة".
سيتم إنشاء المعاينة المباشرة مع ظهور تحذيرات!
خدمة البث المباشر متاحة لتكرار تحديثات الوثائق الخاصة بك. أثناء قيامك بتحديث الأشياء، قد تحدث مشكلة في الترميز. المشكلات التي تعتبر "تحذيرًا" ستؤدي إلى فشل البنية القياسية، ولكن خدمة البث المباشر معدة للإشارة إلى التحذيرات في إخراج وحدة التحكم، مع الاستمرار في البنية. هذا يسمح لك بالتكرار دون الحاجة إلى إعادة تشغيل المعاينة المباشرة.
يختلف "التحذير" عن "الخطأ". إذا أدخلت مشكلة تعتبر "خطأ"، فسوف يفشل الخادم المباشر، وسيتطلب إعادة التشغيل. ولن يعمل مرة أخرى حتى يتم حل مشكلة "التحذير".
لبدء تشغيل الخادم المباشر:
(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.
توثيق linting¶
ستحدد عملية البناء مشاكل Markdown، ولكن BeeWare تقوم ببعض الفحوصات الإضافية للنمط والتنسيق، والمعروفة باسم "linting". لتشغيل فحوصات lint:
(venv) $ tox -e docs-lint
(venv) $ tox -e docs-lint
(venv) C:\...>tox -e docs-lint
سيؤكد ذلك أن الوثائق لا تحتوي على:
- روابط معطلة
- الكلمات المكتوبة بشكل خاطئ
إذا تم تحديد تهجئة صحيحة لكلمة ما على أنها خاطئة، فقم بإضافة الكلمة إلى القائمة
الموجودة في docs/spelling_wordlist. سيؤدي ذلك إلى إضافة الكلمة إلى قاموس
المدقق الإملائي. عند الإضافة إلى هذه القائمة، تذكر ما يلي:
- نفضل استخدام قواعد الإملاء الأمريكية، مع بعض الحرية في استخدام المصطلحات العامية الخاصة بالبرمجة (مثل "apps") وتحويل الأسماء إلى أفعال (مثل "scrollable").
- يجب أن تستخدم أي إشارة إلى اسم منتج الأحرف الكبيرة المفضلة للمنتج. (على سبيل المثال، "macOS" و"GTK" و"pytest" و"Pygame" و"PyScript").
- إذا كان المصطلح يستخدم "ككود"، فيجب اقتباسه حرفياً (
مثل هذا) بدلاً من إضافته إلى القاموس.
بمجرد الانتهاء من إنشاء المستندات بنجاح، تكون جاهزًا لكتابة الوثائق.