المنهج الدراسي الدرس 242 من 250 · مشروع التخرج: شحنه (تغليف مشروعك)
مشروع التخرج: شحنه (تغليف مشروعك)

ملف README + التشغيل بأمر واحد

لديك تخطيط نظيف واختبارات حقيقية. المرحلة الأخيرة هي الجزء الذي يراجعه المراجعون أولا وهو ملف README والأمر الواحد الذي يشغل البرنامج. المشروع الذي يتطلب عشر دقائق من التخمين للبدء يبدو معطلا حتى لو كان يعمل. المشروع الذي يمكنك نسخه وتشغيله بسطر واحد يبدو احترافيا حتى لو كان صغيرا. نفس الكود يؤدي إلى انطباع مختلف تماما.

ملف README هو عقد. يقرأه القارئ بسرعة من الأعلى إلى الأسفل، ويتوقع شكلاً متوقعاً: اسم المشروع كعنوان، ثم كيفية تثبيته، ثم كيفية استخدامه، ثم كيفية اختباره. بشكل ملموس، يحتوي ملف README القوي على سطر عنوان رئيسي (# Something)، ثم هذه الأقسام بهذا الترتيب:

# Triage Copilot

## Setup
pip install -e .            # editable install
cp .env.example .env        # then paste your real key into .env

## Usage
python -m triage            # the one-command run

## Tests
pytest

الترتيب مهم لأن القارئ يتبعه كخطوات. الاستخدام قبل Setup يسبب ارتباكا -> لا يمكنك استخدام ما لم تقم بتثبيته. لذا تكتب checker، validate_readme(text)، يعيد True فقط إذا ظهر عنوان # ، يليه ## Setup، ثم ## Usage، ثم ## Tests، كل واحد بعد الذي قبله. القسم المفقود، أو الأقسام غير المرتبة، تعيد False. الحيلة: مر على الأسطر مرة واحدة، حافظ على "cursor" لمكانك، واشترط ظهور كل قسم في موضع بعد الـ cursor.

التشغيل بأمر واحد. لاحظ أن ## Usage السطر أعلاه هو أمر واحد. هذا هو الهدف من هدف Makefile أو justfile مثل make run -> أمر واحد سهل التذكر يشغل المشروع، حتى لا يضطر أحد لتذكر الاستدعاء الكامل. اكتب make_run(name) الذي يعيد سلسلة ذلك الأمر لمشروع، مثل python -m triage (أو make run). يجب أن يتضمن اسم المشروع، مع تطبيقه بشكل موحد كما هو الحال في دليل الحزمة، بحيث ينتج مشروع مختلف أمراً مختلفاً.

ملاحظتان صادقتان وغير مقيمتين للمستودع الحقيقي. أولا، الأسرار: خطوة cp .env.example .env موجودة لأن مفتاح API الحقيقي يوضع في .env، والذي تضيفه إلى .gitignore و never commit. أنت تلتزم فقط بـ .env.example -> شكل shape للإعدادات مع قيم مؤقتة. تسريب مفتاح إلى مستودع عام هو خطأ مشروع المحفظة الكلاسيكي. ثانيا، deploying this: لوضعه على الإنترنت ستقوم بكتابة Dockerfile صغير (انسخ المستودع، pip install، واضبط أمر التشغيل كنقطة دخول) والدفع إلى PaaS مثل Render أو Railway أو Fly. هذا الجزء لا يمكن تشغيله أو تقييمه في متصفحك -> هو لك لتقوم به عند النشر. اضغط Run للتحقق من README كامل وطباعة أمر التشغيل.

دورك

اكتب الجزأين الحتميين لملف README جيد. تعيد validate_readme(text) قيمة True إذا ظهر عنوان #  في المستوى الأعلى، ثم ## Setup، ثم ## Usage، ثم ## Tests، كل واحد بعد الذي يسبقه (قسم مفقود أو أقسام غير مرتبة -> False). تعيد make_run(name) سلسلة التشغيل بأمر واحد (مثل python -m <pkg> أو make run) التي تدمج اسم المشروع، بشكل موحد مثل دليل الحزمة، بحيث يؤدي اسم مختلف إلى أمر مختلف.

هل لاحظت مشكلة في هذا الدرس؟ أبلغ عنها · اسأل عن هذا الدرس

سيفتح هذا التمرين قريبا

أنهِ الدرس السابق ليفتح هذا الدرس. الدورة كاملة مجانية، ولا تحتاج إلى حساب، ويمكنك قراءة هذا الدرس الآن.