إنشاء توثيق المشروع باستخدام GitHub Copilot

مكتمل

تصف وثائق المشروع الغرض من المشروع وأهدافه ومتطلباته. لإنشاء وثائق المشروع، تحتاج إلى فهم بنية المشروع ومكوناته وكيفية تفاعل المكونات مع بعضها البعض.

تعد واجهة الدردشة في GitHub Copilot أداة مثالية لإنشاء توثيق المشروع، لأنها تستطيع تحليل هيكل المشروع بالكامل وتقديم نظرة عامة عالية المستوى على المشروع. يمكن أيضا استخدام طريقة عرض الدردشة لإنشاء أنواع معينة من الوثائق، مثل ملفات README ومراجع واجهة برمجة التطبيقات والمستندات الأخرى المتعلقة بالمشروع.

يمكنك استخدام كل أوضاع عرض الدردشة (اسأل، وكيل، أو خطة) لإنشاء وثائق المشروع. كل وضع له نقاط القوة والضعف الخاصة به. تؤثر مواصفات المشروع والقيود الأخرى على الوضع الذي يجب استخدامه.

هام

عند استخدام عرض الدردشة في وضع الوكيل، كل طلب تدخله يحتسب كطلب مميز واحد، مضروبا في مضاعف النموذج. قد يتطلب GitHub Copilot عدة إجراءات متابعة لإكمال مهمتك، لكن هذه الإجراءات لا تحتسب ضمن استخدام طلبك المميز. فقط المحفزات التي تدخلها يتم تحميلها. إجمالي الطلبات المميزة المستخدمة يعتمد على عدد الطلبات التي تدخلها والنموذج الذي تختاره.

إنشاء متطلبات وثائق المشروع

تعتمد أنواع الوثائق ومتطلبات المحتوى على المشروع والمستهلكين المقصودين والمعايير التي تعتمدها المؤسسة.

على سبيل المثال، يمكن أن تتضمن README.md الأقسام التالية:

• عنوان المشروع: اسم المشروع.
• الوصف: نظرة عامة موجزة على ما يفعله المشروع وسبب وجوده.
• جدول المحتويات: اختياري، ولكنه مفيد لفترة أطول READMEs.
• التثبيت: إرشادات حول كيفية تثبيت المشروع وإعداده.
• الاستخدام: أمثلة حول كيفية استخدام المشروع، بما في ذلك قصاصات التعليمات البرمجية أو لقطات الشاشة.
• الميزات: قائمة بالميزات أو الوظائف الرئيسية.
• التكوين: تفاصيل حول أي خيارات تكوين أو متغيرات البيئة.
• المساهمة: إرشادات المساهمة في المشروع.
• الترخيص: أي تراخيص يستخدمها المشروع الموزع.
• الاعتمادات والإقرارات: التعرف على المساهمين أو المكتبات أو الموارد المستخدمة.
• جهة الاتصال: كيفية الوصول إلى القائمين على الصيانة أو فريق المشروع.
• Changelog: محفوظات التغييرات والتحديثات (مرتبطة أحيانا بملف منفصل).

يمكن ل GitHub Copilot Chat مساعدتك في إنشاء توثيق المشروع الذي يلبي الاحتياجات الخاصة لمشروعك وأصحاب المصلحة فيه.

استخدم وضع اسأل الوكيل لإنشاء وثائق المشروع

يمكن استخدام وضع وكيل السؤال لتحليل مساحة العمل ثم توليد الوثائق.

استخدم العملية التالية لإنشاء وثائق المشروع باستخدام وضع وكيل السؤال:

1. تحديد متطلبات الوثائق والموارد الداعمة.

   • تحديد متطلبات الوثائق لمشروعك. تحديد أنواع الوثائق وأقسام المستندات المطلوبة.

   • تحديد الموارد المطلوبة لإنشاء الوثائق. يمكن أن تكون مساحة عمل التعليمات البرمجية المورد المطلوب الوحيد. ومع ذلك، قد تحتاج إلى إضافة سياق إلى الدردشة لأقسام مثل "المساهمة" و"الاعتمادات" و"جهة الاتصال".

2. افتح عرض الدردشة وابدأ جلسة دردشة جديدة باستخدام وضع اسأل الوكيل.

3. إضافة سياق إلى جلسة عمل الدردشة.

   • يمكنك إضافة سياق لجلسة الدردشة عن طريق سحب وإفلات الملفات من عرض EXPLORER الخاص ب تعليمة Visual Studio برمجية إلى عرض الدردشة. يمكنك أيضا استخدام زر إرفاق السياق (أيقونة مشبك الورق).
   • يمكنك فتح الملفات الخارجية في محرر التعليمات البرمجية لتضمين الموارد التي ليست جزءا من مساحة العمل واستخدامها لتوفير المزيد من السياق. على سبيل المثال، يمكنك فتح ملفات markdown التي تحتوي على إرشادات المساهمين أو معلومات الاتصال ثم استخدام زر Attach Context لإضافتها إلى سياق عرض الدردشة.

4. أدخل سلسلة من المطالبات التي تحقق من متطلبات الوثائق الخاصة بك.

   يمكنك استخدام وضع اسأل الوكيل لتحليل مساحة العمل وبناء سجل جلسة محادثة يدعم متطلبات التوثيق الخاصة بك. يمكن أن يساعد وصف أهدافك في إنشاء سياق لجلسة الدردشة. طرح الأسئلة التي تلبي متطلباتك يساعد GitHub Copilot تحديد المعلومات اللازمة لإنشاء الوثائق.

   تحديث السياق المضاف حسب الحاجة.

5. أدخل مطالبة تطلب وثائق المشروع المقترحة، مع سرد الأقسام المطلوبة التي حددتها في الخطوة الأولى.

   على سبيل المثال: "/explain #codebase I need help creating a README file that can be used in the GitHub repository for this workspace. The file should be formatted as markdown. The README file needs to include the following sections: Project Title, Description, Table of Contents, Installation, Usage, Features, Configuration, and License."

6. راجع وثائق المشروع المقترحة، وصقل النتائج باستخدام مطالبات جديدة إذا لزم الأمر.

7. انقل وثائق المشروع المقترحة إلى ملف وثائق المشروع.

   على سبيل المثال، إنشاء ملف README.md في جذر مساحة العمل، وإدراج المحتوى المقترح في الملف.

   يمكنك استخدام وضع اسأل الوكيل لاقتراح تحديثات لأقسام محددة من مشروعك بعد إنشاء المستند، أو استخدام أدوات GitHub Copilot أخرى للمساعدة في التحديثات.

استخدم وضع الخطة لإنشاء توثيق المشروع

وضع الخطة هو الأفضل لإنشاء خطة تنفيذ مفصلة قبل إنشاء وثائق المشروع. يقوم وضع الخطة بتحليل قاعدة الشيفرة، وتحديد متطلبات التوثيق، وإنتاج خطة خطوة بخطوة. بمجرد الموافقة على الخطة، يمكنك تسليمها إلى وضع الوكيل لتنفيذها.

استخدم العملية التالية لإنشاء وثائق المشروع، مثل ملف README.md، باستخدام وضع الخطة:

1. تحديد متطلبات الوثائق والموارد الداعمة.

2. افتح عرض الدردشة وابدأ جلسة دردشة جديدة باستخدام وضع الخطة.

3. أدخل تنبيه يصف مهمة التوثيق الخاصة بك.

   على سبيل المثال: "أحتاج إلى إنشاء ملف README ووثائق داعمة لهذا المشروع. يجب أن يتضمن ملف README: عنوان المشروع، الوصف، جدول المحتويات، التثبيت، الاستخدام، الميزات، التكوين، والترخيص."

4. راجع خطة التنفيذ.

   بعد لحظات، يعرض وكيل الخطة خطة في عرض الدردشة. توفر الخطة ملخصا عاما وتفصيلا للخطوات، بما في ذلك أي أسئلة مفتوحة للتوضيح. يمكنك التكرار عدة مرات لتوضيح المتطلبات، أو تعديل النطاق، أو الإجابة على الأسئلة.

5. بمجرد اكتمال الخطة، اختر بدء التنفيذ لتسليم الخطة إلى وضع الوكيل، أو اختر فتح في المحرر لحفظ الخطة كملف Markdown للاستخدام لاحقا.

   عند اختيار بدء التنفيذ، ينتقل GitHub Copilot إلى وضع الوكيل ويبدأ تنفيذ الوثائق بناء على الخطة المعتمدة. راجع ملفات الوثائق التي تم إنشاؤها واقبل أو تجاهل التغييرات.

استخدام وضع العامل لإنشاء وثائق المشروع

وضع العامل هو الأفضل لإنشاء وثائق المشروع التي تتطلب فهما متعمقا للمشروع. يحلل وضع العامل بنية المشروع بالكامل قبل أن ينشئ وثائق المشروع. من خلال جمع المعلومات من ملفات ومجلدات متعددة، يمكن لوضع العامل وصف العلاقات المعقدة وتضمين ارتباطات بين المستندات.

استخدم العملية التالية لإنشاء وثائق المشروع، مثل ملف README.md، باستخدام وضع الوكيل:

1. تحديد متطلبات الوثائق والموارد الداعمة.

2. افتح طريقة عرض الدردشة وابدأ جلسة دردشة جديدة باستخدام وضع العامل.

3. إضافة سياق إلى جلسة عمل الدردشة.

   لا يتوفر المشاركون في الدردشة في وضع العامل، لذلك لا يمكنك تحديد @terminal كجزء من مطالبتك. ومع ذلك، يمكنك إضافة سياق إلى جلسة عمل الدردشة باستخدام #codebase وإضافة ملفات ومجلدات مساحة العمل إلى سياق الدردشة. يمكن فتح الملفات الخارجية في تعليمة Visual Studio برمجية ثم إضافتها إلى سياق الدردشة باستخدام زر Attach Context.

4. أدخل مطالبة لإنشاء وثائق المشروع المقصودة.

   على سبيل المثال: "إنشاء مجموعة من ملفات وثائق المشروع. إنشاء أو تحديث ملف README.md مساحة العمل لهذا المستودع. إنشاء ملف UsageExamples.md أو تحديثه. إنشاء ملف ChangeLog.md أو تحديثه. قم بتضمين الارتباطات بين ملفات الوثائق والفئات والأساليب المرجعية الترافقية، وضمان التناسق عبر المستندات."

5. راجع ملفات المستندات ثم احفظ التحديثات أو تجاهلها.

   قم بتحديث الملف باستخدام المطالبات لتصحيح مقاطع معينة أو تحسينها إذا لزم الأمر.

قدرات وضع العامل

هناك العديد من مهام الوثائق حيث يكون وضع العامل هو الخيار الأفضل.

1. إنشاء وثائق متعددة الملفات والملفات المشتركة.

   • يمكن لوضع العامل تحليل بنية المشروع بأكملها، وجمع المعلومات من ملفات ومجلدات متعددة، وإنشاء وثائق تربط المحتوى وتلخصه عبر قاعدة التعليمات البرمجية. على سبيل المثال، إنشاء مرجع واجهة برمجة تطبيقات كامل أو ملف تمهيدي يصف جميع المكونات الرئيسية.

2. التحليل التلقائي للمشروع وتلخيصه.

   • يمكن لوضع العامل تنفيذ مهام مثل تلخيص البنية، وتحديد الفئات/الخدمات الرئيسية، وإنتاج الرسومات التخطيطية أو الجداول التي تتطلب فهم العلاقات بين الملفات والمكونات.

3. إنشاء محتوى ديناميكي (على سبيل المثال، أمثلة الاستخدام وجداول الفئات)

   • يمكن لوضع العامل مسح المشروع ضوئيا لإنشاء أمثلة استخدام أو جداول مسؤولية الفئة أو قوائم واجهات برمجة التطبيقات العامة.

4. مهام وثائق الدفعات.

   • يمكن لوضع العامل تنفيذ سلسلة من مهام الوثائق (على سبيل المثال، تحديث README، وإنشاء CONTRIBUTING.md، وإنشاء مستندات واجهة برمجة التطبيقات، وتحديث سجل التغيير) في سير عمل واحد.

5. الارتباط الذكي والتنقل.

   • يمكن لوضع العامل إنشاء ارتباطات بين ملفات الوثائق والفئات والأساليب ذات الإسناد الترافقي، وضمان التناسق عبر المستندات.

يعد وضع العامل مثاليا لمهام الوثائق متعددة الملفات والمدركة للسياق على مستوى المشروع والتي تتطلب تحليلا وتركيبا وتنسيقا.

ملخص

يمكن GitHub Copilot مساعدتك في إنشاء توثيق المشروع الذي يلبي الاحتياجات الخاصة لمشروعك وأصحاب المصلحة فيه. يمكن استخدام عرض الدردشة لإنشاء وثائق المشروع بثلاثة أوضاع مختلفة: السؤال، الوكيل، والتخطيط. كل وضع له نقاط القوة والضعف الخاصة به، وأفضل وضع لاستخدام يعتمد على المهمة المحددة في متناول اليد. وضع اسأل الوكيل هو الأفضل لطرح الأسئلة حول قاعدة الكود أو مفاهيم التكنولوجيا. وضع الوكيل هو الأفضل لإنشاء توثيق المشروع الذي يتطلب فهما معمقا للمشروع. وضع الخطة هو الأفضل لإنشاء خطة تنفيذ مفصلة قبل إنشاء الوثائق، والتي يمكن بعد ذلك تسليمها إلى وضع الوكيل للتنفيذ.