تحتوي هذه الصفحة على تفاصيل مشروع كتابة فنية تم قبوله في "موسم مستندات Google".
ملخّص المشروع
- مؤسسة مفتوحة المصدر:
- AboutCode
- الكاتب الفني:
- ayansinha
- اسم المشروع:
- مرجع لخيارات سطر الأوامر في helpcode- Toolkit وأعِد تنظيم بنية مستنداتAboutCode على الرابط aboutcode.readthedocs.io.
- مدة المشروع:
- المدة العادية (3 أشهر)
وصف المشروع
[ 1. خيارات سطر أوامر Scancode-Toolkit ]
يشتمل Scancode-Toolkit على مجموعة من خيارات سطر الأوامر لتخصيص كيفية إجراء الفحص وتنسيق الإخراج والعديد من الخيارات الأخرى مثل المكوّنات الإضافية لما بعد الفحص. لا تتوفّر حاليًا مستندات توضيحية لهذه الخيارات، ولا يمكن استخدامها إلا من خلال العلامة "--help" أو "-h". يهدف هذا المشروع إلى إنشاء مستندات كاملة توضّح ما يلي:
[ 1. جميع الخيارات المتاحة من خلال سطر الأوامر ]
- الهدف: قائمة شاملة بكل الخيارات الممكنة من خلال سطر الأوامر
- نظرة عامة أساسية: أولاً، تتم مناقشة خيارات المسح التلقائية، مع تقديم مثال على الإخراج. رسم بياني/وصف موجز لكيفية إجراء عملية المسح
من الآن فصاعدًا، سيُستخدَم هذا السلوك التلقائي كمرجع لكيفية تغيير الخيارات الأخرى للفحص والنتيجة.
ستتم مناقشة هذه المسائل بالتفصيل وستتضمّن المعلومات التالية كما هو موضّح في الأقسام التالية.
[ 2. بدء بنية تحديد الإصدارات ]
- الهدف: بدء نظام تحديد الإصدارات للحفاظ على التغييرات في خيارات/واجهات برمجة التطبيقات والمستندات على مستوى جميع الإصدارات
- المشكلة: في الوقت الحالي الوثائق الموجودة في موقع wiki وصفحات ReadThe Docs خاصة بالإصدارات القديمة وتحتاج إلى إعادة هيكلة كبيرة.
- نظرة عامة أساسية: في ما يلي أجزاء مجموعة أدوات رموز الاستيلاء التي تم تعديلها/يمكن تعديلها في الإصدار:
- خيارات سطر الأوامر
- واجهات برمجة التطبيقات
- المستندات (سيتم بدء العمل عليها) يتم تغيير خيارات سطر الأوامر وواجهات برمجة التطبيقات في الإصدارات، ويجب أن تتّبع المستندات ذلك أيضًا، وإلا سيؤدي ذلك إلى حدوث ارتباك كبير لدى المستخدمين. تم تعديل الأداة التي تعمل على سطر الأوامر [ --help ] لأي تغييرات في الخيارات، ويمكن استخدامها لتكرار نظام الإصدار في المستندات.
[ 3. كيفية استخدام هذه الخيارات في حالات مختلفة ]
- الهدف: سيقدّم هذا القسم ملخّصًا أساسيًا لكيفية استخدام نتائج المسح الضوئي لأداة Scancode-Toolkit في أسباب مختلفة وخيارات Scancode-Toolkit التي توفّر هذه الوظيفة.
- نظرة عامة أساسية: يقدّم هذا القسم أمثلة مختلفة لسيناريو حالة الاستخدام والخيارات المقترَحة في تلك السيناريوهات.
- ملاحظة: يتطلب هذا الجزء مساعدة كبيرة من المرشد من حيث المدخلات حول حالات الاستخدام المختلفة لأداة Scancode-Toolkit وتوجيهات بشأنها.
[ 4- ما الذي تغيره هذه الخيارات في الفحص والإخراج ]
- الهدف: سيقدّم هذا القسم ملخّصًا أساسيًا لكيفية استخدام نتائج المسح الضوئي من أداة scancode-toolkit في أسباب مختلفة، وأدوات Aboutcode التي توفّر هذه الوظيفة.
- نظرة عامة أساسية: تعمل الخيارات على تغيير سلوك طريقة إجراء عملية المسح. سيتم توضيح حالة تلقائية أساسية في القسم الرئيسي [ 1. جميع الخيارات المتاحة من خلال سطر الأوامر ] سيقارن هذا القسم التغييرات التي تحقّقها جميع الخيارات في هذا السيناريو التلقائي.
[ 5. تنسيقات الإخراج وأمثلة عليها ]
- الهدف: سيقدّم هذا القسم ملخّصًا أساسيًا لكيفية استخدام نتائج المسح الضوئي من أداة scancode-toolkit في أسباب مختلفة، وأدوات Aboutcode التي توفّر هذه الوظيفة.
- نظرة عامة أساسية: تحتوي أداة Scancode على علامات لتحديد تنسيقات الإخراج المختلفة التي سيتم إنشاء نتائج المسح فيها. وهي:
سيتناول هذا الجزء - شرح تنسيقات الإخراج بالتفصيل
- تقديم أمثلة على تنسيقات النتائج
- منح روابط أخرى تتوافق مع تنسيق الإخراج واستخدامه
- كيفية تخزين نتائج المسح في ملفات الإخراج يرتبط هذا أيضًا بطريقة إنشاء هذه التنسيقات المختلفة، والتي سيتم شرحها في [ 2. مناقشات تشرح مسح الرموز ].
[ 6. استخدام التنسيقات الناتجة عن الرموز المخصّصة للمسح الضوئي في الأنشطة التجارية ]
- الأهداف: توضيح حالات استخدام تنسيقات نتائج رموز الاستيلاء على البيانات في مجال الأعمال في قائمة أفكار GSoD، تم ذكر تنسيقات نتائج رموز الاستيلاء على البيانات كفكرة مرجعية. ينفِّذ هذا القسم الإجراء نفسه.
- ملاحظة: يتطلب هذا الجزء مساعدة كبيرة من الموجه في ما يتعلق بالمدخلات والمؤشرات المتعلقة بمختلف حالات الاستخدام التجاري الخاصة بـ Scancode-Toolkit.
[ 7. كيفية استخدام هذه النتائج من خلال مشاريع لمحة عن الرمز البرمجي الأخرى لمزيد من التحليل ]
- الهدف: سيقدّم هذا القسم ملخّصًا أساسيًا لكيفية استخدام نتائج المسح الضوئي من أداة scancode-toolkit في أسباب مختلفة، وأدوات Aboutcode التي توفّر هذه الوظيفة.
- نظرة عامة أساسية:
- Scancode-Workbench يوضّح هذا الجزء كيفية عرض النتائج باستخدام تطبيق الكمبيوتر المكتبي ومؤشرات إلى مستندات Scancode-workbench للحصول على مزيد من الدعم بشأن ذلك. سيتمّ إضافة المستندات المطلوبة إلى scancode-workbench إذا لزم الأمر.
- Deltacode كيفية حصول Deltacode على نتائج رمز المسح الضوئي لتحديد الاختلافات على مستوى الملف بين قاعدتَي بيانات
[ 2- إعادة تنظيم بنية مستندات AboutCode ]
يتضمن هذا الجزء مجموعة من التغييرات التي تم إجراؤها على وثائق رمز لمحة
[ 1. نظام تحديد الإصدارات ]
في [ 1. خيارات سطر أوامر Scancode-Toolkit -> 2. بدء بنية الإصدار] تم ذكر مشكلة إصدار خيارات سطر الأوامر. وينطبق الأمر نفسه على الأجزاء الأخرى من المستندات التي تحتوي على أوامر أو معلومات خاصة بالإصدار، والتي قد تؤدي إلى حدوث التباس.
[ 2. إعداد معايير المستندات والاختبارات ]
تتضمّن المستندات حاليًا اختبارات لبرنامج spinx-build (الذي ينشئ جميع الصفحات ويتحقّق من أخطاء بنية Sphinx في جميع أنحاء البرنامج) وفحص الروابط (الذي يتحقّق من جميع الروابط المؤدية إلى صفحات ويب أخرى من المستندات) من خلال عملية الدمج المستمر من خلال Travis-CI. (تمت إضافتها في طلب السحب رقم 17 هذا) تحتاج الآن إلى المزيد من عمليات التحقق من استخدام أداة لينوطة معينة في النص المُعاد تنظيمه والمعايير الأخرى. يمكن تحقيق ذلك باستخدام أداة Lint مع إعادة هيكلة النص، ولكنّه يحتاج إلى مزيد من الأبحاث وسيتم تنفيذه كجزء من مشروع GSoD الخاص بي.
[ 3- إضافة قسم "البدء" ]
سيكون هذا بمثابة قسم بداية للمستخدمين الجدد وسيتضمن مجموعة من المستندات الأساسية والمهمة لبدء استخدام مشاريع لمحة عن الرمز. سيتضمّن كل مشروع Aboutcode هذا القسم، بما في ذلك Scancode-Toolkit وScancode-Workbench وDeltacode وغيرها.
[ 4- إعادة التنظيم وفقًا لوظائف المستندات الأربعة ]
لا يتم تنظيم "المستندات" الحالية بشكل صريح في وظائف المستندات الأربعة: الأدلة الإرشادية والأدلة الإجرائية والمراجع والشروحات. نقترح تنظيم هذه العناصر وفقًا لذلك، مع إضافة المزيد من المعلومات أو التفسيرات أو الإشارات كلما لزم الأمر. وينطبق ذلك على جميع مشاريع AboutCode ووثائقها. في ما يلي مثالان على إعادة هيكلة مستندات Scancode-Toolkit التي أقترحها وأريد مواصلة العمل عليها في هذا المشروع. وسيتم إجراء تغييرات مماثلة على بقية المستندات.
[ 5. إعادة هيكلة صفحة التطوير (Scancode-Toolkit) ]
يمكن إضافة مزيد من المعلومات حول الرموز البرمجية أو واجهات برمجة التطبيقات لتسهيل استخدامها على المطوّرين. يمكن أن تتضمّن روابط إلى [ 2. مناقشات تشرح قسم مسح الرموز ] أعلاه. يربط هذا الإجراء شرح طريقة عمل عملية المسح بالرمز البرمجي الذي يستخدمه لإجراء عملية المسح. بما أنّ هذه المجلدات تحتوي على أجزاء مختلفة من مجموعة أدوات رموز الاستيلاء، يمكن توضيح استخدامها الفردي باستخدام واجهات برمجة التطبيقات، إلى جانب المناقشة حول آلية عمل رموز الاستيلاء.
- [ cluecode : plugins for scanning licenses, copyrights, urls, emails ]
- [commoncode : فئات ودوال مساعدة]
- [ extractcode : extracts different archive formats ]
- [ formattedcode : output formatting for different output file formats ]
- [ licensedcode : licence detection code ]
- [ packagedcode : تحليل تنسيقات حزم متنوعة ]
- [ plugincode : classes for the plugins architecture ]
- [ summarycode : summarizes scan on detected licenses ]
- [ textcode : handles text parsing ]
- [ typecode : معالجة تحديدات نوع الملف ]
- [ مسح رمز مسح : واجهة سطر الأوامر وواجهة برمجة التطبيقات ضوئيًا، الجزء الأساسي ]
سيتضمّن هذا القسم الفرعي معلومات/واجهات برمجة تطبيقات تفصيلية حول هذه الأجزاء من مجموعة أدوات رموز الاستيلاء في الأقسام الفرعية وفقًا لذلك. ستظهر إرشادات التطوير في صفحة أخرى أو قسم آخر يتضمّن أقسامًا فرعية أصغر.
[ 6. إعادة هيكلة صفحة الأسئلة الشائعة (Scancode-Toolkit) ]
تحتوي صفحة الأسئلة الشائعة في الوقت الحالي على أسئلة يمكن الإجابة عليها بشكل أفضل ويجب هيكلتها كمستندات منفصلة لبرامج توجيهية وبرامج تعليمية ومرجعية بشكل منفصل.
- كيف يعمل ScanCode؟ تتم الإشارة إلى هذه المشكلة في [ 2. مناقشات توضّح ميزة "مسح الرموز ضوئيًا"] وسيكون قسمًا منفصلاً تمامًا يتضمّن المزيد من التفاصيل.
- كيف يمكن إضافة قواعد ترخيص جديدة لميزة "الكشف المحسَّن"؟ سبق أن تمت مناقشة هذه المشكلة في قسم "تحسين التعليمات الحالية"، وسيتم نقل المستندات إلى هناك.
- كيف يمكن إضافة قاعدة جديدة لرصد الترخيص؟ يمكن شرح هذا الأمر في مشاركة أخرى حول "كيفية التنفيذ" بشكل منفصل ويمكن شرحه بالتفصيل.
- How To get started with Development? وهناك بالفعل صفحة تطوير منفصلة وتتداخل المعلومات إلى حد كبير. سبق أن تمت مناقشة إعادة هيكلة صفحة التطوير أعلاه.
- خطوات إنشاء إصدار جديد يمكن تحويل هذه الخطوات إلى مقالة منفصلة بعنوان "كيفية إنشاء إصدار جديد".
- ابحث عن المزيد من الأسئلة الشائعة التي تجيب عن أسئلة عامة حول المشروع ولا تندرج ضمن فئات "الدليل التعليمي" أو "كيفية".