تستفيد أغلب مشاريع البرمجيات من وجود قطعة من الوثائق التي توفر دليلاً سريعًا للبدء في إعداد المشروع واستخدامه والمساهمة فيه. وينطبق هذا بشكل خاص على المشاريع مفتوحة المصدر حيث ترغب عادةً في جذب المستخدمين والمساهمين. يُعرف هذا النوع من المستندات عادةً باسم ملف README، ويجب عليك إضافة ملف واحد إلى كل مشروع بايثون تقوم بإنشائه.
في هذا الدرس، سوف تتعلم:
- ما هو ملف README
- كيفية تنظيم ملف README
- ما هو تنسيق المستند الذي يجب استخدامه لملفات README
- كيفية تحضير ملف README لمنصات مثل PyPI وGitHub
- ما هي الأدوات والقوالب التي يجب استخدامها لإنشاء ملفات README
لن تحتاج إلى معرفة خاصة لقراءة هذا الدرس. ومع ذلك، لبدء إنشاء ملفات README الخاصة بك، يجب أن تتعرف على لغات الترميز، مثل Markdown وreStructuredText.
ما هو ملف README؟
ملف README هو مستند تقوم عادةً بإضافته إلى الدليل الجذر لمشروع برمجي. وهو غالبًا ما يكون دليلاً موجزًا يوفر معلومات أساسية حول المشروع. ويهدف ملف README إلى مساعدة المستخدمين والمطورين على فهم غرض المشروع وكيفية استخدامه وكيفية المساهمة فيه. كما أنه وسيلة للتواصل مع المستخدمين المحتملين والمتعاونين والمساهمين.
ملفات README هي عادةً ملفات نصية عادية وهي الجزء الأكثر وضوحًا من الوثائق وغالبًا ما تكون صفحة الوصول للعديد من مشاريع البرمجيات، بما في ذلك مشاريع المصدر المفتوح.
يجب أن يحتوي ملف README فقط على المعلومات الضرورية للمستخدمين والمتعاونين والمطورين للبدء في استخدام مشروعك والمساهمة فيه. للحصول على وثائق أكثر توسعًا، فإن الويكيات أو صفحات الوثائق المخصصة هي الأنسب والموصى بها.
لماذا تحتاج إلى ملف README في مشاريع بايثون؟
تتمتع ملفات README بتاريخ طويل في البرمجيات الحرة والمفتوحة المصدر. تشجعك معايير GNU Coding على تضمين ملف README لتوفير نظرة عامة على محتويات الحزمة. ومع ذلك، لا يقتصر هذا النوع من الملفات على المشاريع الحرة والمفتوحة المصدر. يمكنك إضافة ملف README إلى أي مشروع تريده.
لماذا يجب عليك قضاء وقت في كتابة ملف README لمشاريع بايثون؟ فيما يلي بعض الأسباب العامة:
- ملفات README هي نوع من المعايير في صناعة البرمجيات.
- غالبًا ما يكون ملف README هو أول شيء يلاحظه المستخدمون أو يبحثون عنه عندما يجدون مشروعك.
- يساعدك ملف README الجيد على تمييز مشروعك عن المشاريع الأخرى.
- ملف README عالي الجودة يميز المشروع الجيد عن المشروع السيئ.
- غالبًا ما يتم عرض ملفات README كصفحة هبوط للمشروع على منصات تطوير البرامج مثل GitHub و GitLab.
من وجهة نظر أكثر تخصصًا، يمكن لملف README الجيد أن يساعدك في:
- قم بتقديم المشروع من خلال تقديم نظرة عامة حول ما يتعلق به المشروع، والغرض منه، وميزاته الرئيسية.
- تقديم التوجيه من خلال تقديم تعليمات حول كيفية إعداد المشروع للاستخدام والمساهمات.
- اجتذاب المساهمين من خلال تقديم إرشادات واضحة حول كيفية المساهمة في المشروع.
- توفير التوثيق من خلال العمل كمصدر أساسي للتوثيق للمشروع.
- توفير الدعم ومعلومات الاتصال من خلال تقديم تفاصيل حول كيفية الحصول على المساعدة أو الاتصال بصيانة المشروع.
- قم بتضمين معلومات الترخيص من خلال تحديد الشروط الخاصة باستخدام المشروع والمساهمة فيه.
هذه مجرد بعض الفوائد المترتبة على إضافة ملف README إلى مشاريع بايثون. إذًا، ما رأيك؟ هل يستحق الأمر إضافته؟
ما هو الهيكل المعتاد لملف README الكبير؟
أولاً، يجب أن تعلم أنه لا توجد طريقة صحيحة واحدة لتنظيم ملف README عالي الجودة. في الممارسة العملية، يعتمد المحتوى والأقسام التي تدرجها في هذا الملف على مشروعك المحدد. ومع ذلك، ستجد أن معظم ملفات README تحتوي على أقسام مشتركة، مثل اسم المشروع، والتعليمات حول كيفية إعداد المشروع واستخدامه، والإرشادات الخاصة بالمساهمة في المشروع، وموضوعات مماثلة.
في الأقسام التالية، ستتعرف على الأقسام الأكثر استخدامًا في ملفات README ومحتواها.
الأقسام الشائعة في ملفات README الرائعة
قبل مناقشة كيفية تنظيم ملف README في مستند منظم جيدًا يحتوي على أقسام ذات صلة، ستنظر بإيجاز في المحتوى العام الذي تحتوي عليه معظم ملفات README. للتعامل مع هذا الموضوع لمشروع بايثون معين، حاول الإجابة على الأسئلة التالية:
- ما هو دافعك لبناء المشروع؟
- ما هي المشكلة التي يحلها المشروع؟
- ما هي التقنيات التي يستخدمها المشروع ولماذا؟
- ما هي أهم مميزات المشروع؟
- كيف يمكن للمستخدمين البدء بالمشروع؟
- أين يمكن للمستخدمين الحصول على المساعدة فيما يتعلق بمشروعك؟
بمجرد أن تفكر في هذه الأسئلة، سيكون لديك معلومات أساسية كافية لبدء كتابة ملف README الخاص بمشروعك. أولاً، يجب أن يكون لديك اسم معقول وسهل القراءة وجذاب لمشروعك. غالبًا ما تكون هذه خطوة صعبة بشكل مدهش!
بمجرد أن يكون لديك اسم، يمكنك البدء في التفكير في المحتوى الذي يجب تضمينه في ملف README الخاص بالمشروع. فيما يلي قائمة سريعة وغير شاملة للموضوعات الشائعة. لاحظ أن بعض هذه الأقسام ذات صلة فقط بالمشاريع مفتوحة المصدر:
- وصف المشروع: وصف موجز لما يفعله مشروعك. إحدى الطرق الجيدة للقيام بذلك بشكل صحيح هي تقديم:
- فقرة موجزة تصف مشروعك
- لقطة شاشة تمثيلية أو صورة GIF متحركة تعرض مشروعك أثناء العمل
- التثبيت: سلسلة من الخطوات التي تصف كيفية تثبيت المشروع. إذا كان مشروعك متعدد الأنظمة الأساسية، فتأكد من إدراج الخطوات لجميع الأنظمة الأساسية المدعومة.
- التنفيذ والاستخدام: التعليمات الخاصة بتنفيذ المشروع إذا كان تطبيقًا قابلًا للتنفيذ بلغة بايثون. إذا كان المشروع عبارة عن مكتبة بايثون، فيمكنك تقديم بعض أمثلة التعليمات البرمجية لاستخدام المكتبة. ومن الناحية المثالية، يجب عليك تقديم أمثلة تعرض الميزات الأكثر صلة بالمشروع.
- التقنيات المستخدمة: قائمة بالتقنيات المستخدمة، بما في ذلك مكتبات بايثون وأطر العمل التابعة لجهات خارجية. يمكنك تقديم وصف موجز لكل تقنية، واختياريًا، الأسباب وراء استخدامها.
- الميزات الحالية: قائمة بالميزات الحالية. يمكنك الاستفادة من هذا القسم للقيام ببعض التسويق حول مشروعك من خلال تسليط الضوء على أهم ميزاته.
- المساهمة: سلسلة من الخطوات للمساهمة في المشروع. أو يمكنك إنشاء دليل خاص للمساهمين في ملف منفصل، وهو أمر شائع في المشاريع الكبيرة.
- المساهمون: قائمة الأشخاص الذين ساهموا بطريقة ما في مشروع بايثون. إن ذكر المساهمين هو طريقة ممتازة لجعل المساهمين في المشاريع مفتوحة المصدر يشعرون بأنهم جزء من جهد فريق.
- معلومات المؤلف: اسم المؤلف ومعلومات الاتصال به، مثل حسابات وسائل التواصل الاجتماعي والبريد الإلكتروني. ستكون هذه المعلومات مفيدة للأشخاص الذين يرغبون في التعاون معك.
- سجل التغييرات: سجل تغييرات مكثف يسرد التغييرات التي أجريت على المشروع مقارنةً بالإصدار السابق.
- الترخيص: بيان سريع حول الترخيص الذي يعمل البرنامج بموجبه. يمكنك تضمين ملف LICENSE.txt ضمن المجلد الجذر للمشروع ثم ربطه بهذا الملف. بالنسبة لمشروع بايثون مفتوح المصدر، يمكنك الانتقال إلى opensource.org والحصول على الترخيص الذي يلبي احتياجاتك.
مرة أخرى، هذه القائمة من الأقسام ليست شاملة. فهي تحدد فقط الأقسام الأكثر استخدامًا في ملف README النموذجي.
بالنسبة لملفات README التي تكون على الجانب الطويل، يجب عليك تضمين جدول محتويات في بداية الملف لتسهيل التنقل عبر محتوى الملف.
شارات مفيدة لملفات README
إذا كنت تستخدم منصة مثل GitHub لاستضافة الكود المصدري لمشروعك، فيمكنك تضمين بعض الشارات الرائعة في ملف README الخاص بك. الشارات عبارة عن صور صغيرة يمكنك استخدامها في ملفات README الخاصة بـ GitHub أو GitLab. على سبيل المثال، يمكنك إضافة بعض الشارات التالية لتوفير معلومات إضافية حول مشروعك بطريقة مرئية:
- تغطية الكود:
- النسخة المستقرة:
- بايثون:
- SQLite:
- رخصة:
يمكنك إضافة هذه الشارات والعديد من الشارات الأخرى إلى ملف README الخاص بمشروعك كطريقة لعرض التفاصيل الأساسية حول المشروع بصريًا.
للحصول على قائمة بالشارات التي يمكنك استخدامها في ملف README الخاص بمشروعك، ألقي نظرة على مستودع Awesome Badges على GitHub.
أخيرًا، إذا كنت تستخدم GitLab لاستضافة الكود المصدري لمشروعك، فيجب عليك التحقق من الصفحة المتعلقة بالشعارات في وثائقهم الرسمية. ستجد في هذه الصفحة تعليمات مفصلة حول كيفية إعداد الشعارات لمشروع معين.
ما هو تنسيق المستند الذي يمكنك استخدامه لملف README؟
لكتابة ملف README لمشروع بايثون، ستستخدم ملف نص عادي. يمكنك هيكلة محتوى الملف باستخدام لغات ترميز مختلفة. اللغتان الأكثر استخدامًا هما التاليتان:
- Markdown: لغة ترميز خفيفة الوزن تتيح لك تصميم ملف نص عادي باستخدام تقنيات التنسيق مثل العناوين والتأكيد والقوائم والصور والروابط. إنها واحدة من أكثر لغات الترميز شيوعًا في الوقت الحاضر.
- reStructuredText: لغة ترميز نصية بسيطة وسهلة القراءة، ما تراه هو ما تحصل عليه (WYSIWYG)، تستخدم هياكل بديهية للإشارة إلى بنية المستند. وهي تسمح لك بتحديد هياكل، مثل عناوين الأقسام وقوائم النقاط والتأكيد.
فيما يلي مقارنة سريعة بين اللغتين:
| الميزة | Markdown | reStructuredText |
|---|---|---|
| بناء الجملة | بسيطة والحد الأدنى | أكثر تفصيلا وشاملة |
| امتداد الملف | .md | .rst |
| العناوين | #, ##, ###, … | ====, ----, ~~~~, … |
| القوائم | منظم وغير منظم | منظم وغير منظم |
| الروابط | (url) | text <url> |
| الصور |  | .. image:: url |
| التركيز | **bold**, *italic* | **bold**, *italic* |
| كتل التعليمات البرمجية | مسافة بادئة بـ 4 مسافات أو علامات خلفية | مُسافة بادئة بـ 4 مسافات،:: |
| الجداول | دعم الجدول الأساسي | دعم الجدول الأكثر تقدما |
| الحواشي | دعم محدود | دعم أكثر اكتمالا |
| إنشاء جدول المحتويات | محدود | الدعم المدمج |
| الإضافات والمكونات الإضافية | ملحقات متنوعة متاحة | التوجيهات والأدوار المضمنة الغنية |
| حالات الاستخدام | منشورات المدونة، الوثائق، الملاحظات | توثيقات شاملة، كتب |
| تقديم | مدعومة على نطاق واسع | مدعومة من خلال أدوات محددة |
| منحنى التعلم | قليل | متوسطة إلى عالية |
لكل من اللغتين مميزاتها وعيوبها. غالبًا ما يُفضَّل استخدام Markdown لملفات README لأنه في أغلب الحالات لا يتطلب هذا النوع من الملفات تنسيقًا معقدًا. وعلى النقيض من ذلك، إذا كان ملف README الخاص بك يتطلب ميزات تنسيق متقدمة، فقد يكون reStructuredText خيارًا أفضل.
توفر منصات تطوير البرامج الشهيرة عبر الإنترنت، مثل GitHub وGitLab، الدعم للغتي الترميز. عندما يتعلق الأمر بلغة Markdown، فإن كلتا المنصتين لهما نكهتهما الخاصة. إذا كان كود المصدر الخاص بمشروعك مستضافًا في إحدى هذه المنصات، فيجب عليك التحقق من مواصفات Markdown ذات النكهة المقابلة.
كيف يمكنك تحضير ملف README لـ PyPI أو GitHub؟
عند نشر مشاريعك على Python Package Index (PyPI) أو استضافة الكود المصدري للمشروع في نظام أساسي مثل GitHub، قد تحتاج إلى اتباع بعض المتطلبات أو الإرشادات لإنشاء ملفات README الخاصة بك.
في الأقسام التالية، ستتعرف على هذه المتطلبات والمبادئ التوجيهية، مع التركيز على PyPI وGitHub.
ملفات README لـ PyPI
إن وجود ملف README رائع لمشروع بايثون المستضاف في PyPI يمكن أن يساعد في تميزه عن المشاريع المماثلة على المنصة. يخلق ملف README المصمم جيدًا انطباعًا أوليًا جيدًا عن جودة مشروعك.
لكي يتم عرض ملف README بشكل جيد على PyPI، يمكنك استخدام لغة ترميز Markdown أو reStructuredText. يمكنك أيضًا استخدام نص عادي، ولكن عند القيام بذلك، ستكون خيارات التنسيق لديك محدودة.
إذا اخترت لغة Markdown، فيجب عليك استخدام Markdown بنكهة GitHub. من ناحية أخرى، إذا اخترت استخدام reStructuredText، فيمكنك استخدام بناء الجملة القياسي بدون ملحقات Sphinx.
أخيرًا، من المعتاد حفظ ملف README في المجلد الجذر للمشروع. بهذه الطريقة، سيكتشف PyPI تلقائيًا ملف README ويعرضه كصفحة وصول للمشروع.
ملفات README لـ GitHub
عندما تستضيف كود مشروعك على GitHub كمشروع مفتوح المصدر، فيجب عليك استخدام Markdown بنكهة GitHub وحفظ ملف README في المجلد الجذر لمشروعك أو في دليل .github/ أو docs/ الخاص بالمستودع.
إذا وضعت ملف README في أحد هذه المجلدات، فسوف يتعرف عليه GitHub وسيظهر الملف تلقائيًا للزوار الذين يجدون مستودعك.
للتعرف بشكل أعمق على ميزات GitHub المتعلقة بملفات README، راجع صفحة About README. ستجد من بين الموضوعات الأخرى ما يلي:
- جدول محتويات تم إنشاؤه تلقائيًا لملفات README
- روابط الأقسام في ملفات README وصفحات الكائنات
- الروابط النسبية ومسارات الصور في ملفات README
باستخدام هذه الإرشادات، ستتمكن من إنشاء ملف README بسرعة لمشروع جديد أو تخصيص ملف README موجود.
ما هي الأدوات التي يمكنك استخدامها لأتمتة إنشاء ملف README؟
نظرًا لأن ملفات README شائعة جدًا ومفيدة لمشاريع البرامج، فستجد العديد من الأدوات على الإنترنت التي تسمح لك بأتمتة عملية إنشاء ملفات README.
ملاحظة: يمكنك إنشاء ملف README الخاص بمشروعك باستخدام أي محرر نصوص عادي. ولا يلزمك استخدام أداة مخصصة لهذه المهمة.
في الأقسام التالية، سيتم توجيهك إلى بعض الأدوات المتوفرة عبر الإنترنت لإنشاء ملفات README. كما ستتعرف على بعض الأدوات الأخرى التي يمكنك استخدامها لإنشاء ملفات README، بما في ذلك محرري Markdown وreStructuredText عبر الإنترنت.
مولدات README
سيمنحك البحث السريع عن أدوات إنشاء README قائمة بالأدوات المذهلة التي يمكنك استخدامها لأتمتة إنشاء هذه الملفات في مشاريع بايثون. فيما يلي قائمة سريعة ببعض الأدوات المفيدة:
| الأداة | الوصف |
|---|---|
| readme.so | محرر يسمح لك بإضافة وتخصيص جميع الأقسام التي تحتاجها لملف README الخاص بمشروعك بسرعة. |
Make a README | قالب README قابل للتعديل عبر الإنترنت مع عرض Markdown المباشر. |
readme-md-generator | تطبيق واجهة سطر أوامر (CLI) يقوم بإنشاء ملفات README.md. ويقترح إجابات افتراضية من خلال قراءة ملف package.json وإعداد git. |
محررو Markdown عبر الإنترنت
يمكنك أيضًا استخدام محرر Markdown عادي لإنشاء ملفات README الخاصة بمشاريع بايثون الخاصة بك. فيما يلي قائمة سريعة بمحرري Markdown عبر الإنترنت التي يمكنك استخدامها لهذا الغرض:
| المحرر | الوصف |
|---|---|
| StackEdit | محرر Markdown مفتوح المصدر وكامل الميزات يعتمد على PageDown، مكتبة Markdown التي يستخدمها Stack Overflow ومواقع Stack Exchange الأخرى. |
| Dillinger | محرر Markdown متوافق مع السحابة، وجاهز للأجهزة المحمولة، ومتوافق مع التخزين دون اتصال بالإنترنت، ومدعوم بتقنية AngularJS. |
| Online Markdown Editor | محرر Markdown عبر الإنترنت مدعوم من CKEditor. إطار عمل WYSIWYG قوي يوفر تجربة تحرير قابلة للتخصيص بالكامل. |
باستخدام هذه الأدوات عبر الإنترنت، يمكنك إنشاء ملفات README وتحريرها وتنسيقها باستخدام لغة Markdown.
لقد تعلمت كيفية إنشاء ملفات README عالية الجودة وتنظيمها وتنسيقها لمشاريع بايثون. هذا النوع من الملفات عبارة عن قطعة قصيرة من الوثائق التي توفر عادةً نظرة عامة على المشروع، بما في ذلك التعليمات الخاصة بتثبيت المشروع واستخدامه والمساهمة فيه. ملفات README مفيدة بشكل خاص لمشاريع بايثون مفتوحة المصدر.
اكتشاف المزيد من بايثون العربي
اشترك للحصول على أحدث التدوينات المرسلة إلى بريدك الإلكتروني.