تحتوي هذه الصفحة على تفاصيل مشروع كتابة فنية تم قبوله في برنامج Google Season of Docs.
ملخّص المشروع
- مؤسسة مفتوحة المصدر:
- AboutCode
- كاتب فني:
- ayansinha
- اسم المشروع:
- مرجع لخيارات سطر الأوامر في scancode-toolkit وإعادة تنظيم بنية مستندات AboutCode على aboutcode.readthedocs.io
- مدة المشروع:
- المدة العادية (3 أشهر)
وصف المشروع
[ 1. خيارات سطر الأوامر في Scancode-Toolkit ]
يتضمّن Scancode-Toolkit مجموعة من خيارات سطر الأوامر لتخصيص طريقة إجراء الفحص وتنسيق الإخراج والعديد من الخيارات الأخرى، مثل المكوّنات الإضافية بعد الفحص. لا تتوفّر حاليًا مستندات مناسبة لشرح هذه الخيارات، ولا يمكن الوصول إليها إلا من خلال العلامة "--help" أو "-h". يهدف هذا المشروع إلى إنشاء مستندات كاملة توضّح ما يلي:
[ 1. جميع الخيارات المتاحة من خلال سطر الأوامر ]
- الهدف: قائمة شاملة بكل الخيارات الممكنة من خلال سطر الأوامر.
- نظرة عامة أساسية: في البداية، تتم مناقشة خيارات الفحص التلقائية، مع تقديم مثال على الناتج. تمثّل هذه السمة وصفًا موجزًا أو رسمًا بيانيًا يوضّح كيفية إجراء عملية الفحص.
من الآن فصاعدًا، سيكون هذا السلوك التلقائي مرجعًا لكيفية تغيير الخيارات الأخرى لعملية الفحص والناتج.
سيتم مناقشة هذه التقارير بالتفصيل وستتضمّن المعلومات التالية كما هو مذكور في الأقسام التالية.
[ 2. بدء بنية تحديد الإصدارات ]
- الهدف: إنشاء نظام لتحديد الإصدارات من أجل الحفاظ على الخيارات/واجهة برمجة التطبيقات والتغييرات في المستندات بشكلٍ سليم.
- المشكلة: في الوقت الحالي، تتوفّر المستندات في صفحات Wiki وReadTheDocs للإصدارات القديمة، وهي بحاجة إلى إعادة هيكلة كبيرة.
- نظرة عامة أساسية: أجزاء scancode-toolkit التي تم تعديلها/يمكن تعديلها في الإصدار هي
- خيارات سطر الأوامر
- واجهات برمجة التطبيقات
- المستندات (سيتم البدء بها) تتغير خيارات سطر الأوامر وواجهات برمجة التطبيقات في الإصدارات، ويجب أن تتوافق المستندات مع هذه التغييرات، وإلا سيحدث التباس كبير للمستخدمين. تمّ تعديل أداة سطر الأوامر [ --help ] لتشمل أي تغييرات في الخيارات، ويمكن استخدامها لتكرار نظام تحديد الإصدار في المستندات.
[ 3. كيفية استخدام هذه الخيارات في حالات مختلفة ]
- الهدف: سيقدّم هذا القسم ملخّصًا أساسيًا حول كيفية استخدام نتائج فحص scancode-toolkit في حالات مختلفة وخيارات Scancode-Toolkit التي توفّر هذه الوظيفة.
- نظرة عامة أساسية: يقدّم هذا القسم أمثلة مختلفة على سيناريوهات حالات الاستخدام والخيارات التي يُنصح بها في هذه السيناريوهات.
- ملاحظة: يتطلّب هذا الجزء مساعدة كبيرة من المرشد من حيث المدخلات حول حالات الاستخدام المختلفة لأداة Scancode-Toolkit والإشارات إليها.
[ 4. التغييرات التي تحدثها هذه الخيارات في عملية الفحص والنتائج ]
- الهدف: سيقدّم هذا القسم ملخّصًا أساسيًا حول كيفية استخدام نتائج المسح الضوئي التي يوفّرها scancode-toolkit في حالات مختلفة، وأدوات Aboutcode التي توفّر هذه الوظيفة.
- نظرة عامة أساسية: تغيّر الخيارات طريقة إجراء عملية الفحص. سيتم توضيح حالة تلقائية أساسية في القسم الرئيسي [ 1. ستقارن جميع الخيارات المتاحة من خلال "سطر الأوامر" ] وهذا القسم التغييرات التي تحدثها جميع الخيارات في هذا السيناريو التلقائي.
[ 5. تنسيقات الإخراج وأمثلة عليها ]
- الهدف: سيقدّم هذا القسم ملخّصًا أساسيًا حول كيفية استخدام نتائج المسح الضوئي التي يوفّرها scancode-toolkit في حالات مختلفة، وأدوات Aboutcode التي توفّر هذه الوظيفة.
- نظرة عامة أساسية: تحتوي أداة Scancode على علامات لتحديد تنسيقات إخراج مختلفة سيتم إنشاء نتائج الفحص بها. وهي -
سيتناول هذا الجزء - اشرح بالتفصيل تنسيقات الإخراج
- أمثلة على تنسيقات الإخراج
- تقديم روابط أخرى تتوافق مع تنسيق الإخراج واستخدامه
- كيفية تخزين نتائج البحث في ملفات الإخراج يتضمّن هذا القسم أيضًا رابطًا إلى مقالة "كيفية إنشاء هذه التنسيقات المختلفة" التي سيتم شرحها في [ 2. مناقشات تشرح ميزة "فحص الرمز"].
[ 6. استخدام الأعمال لتنسيقات إخراج رمز الاستجابة السريعة ]
- الأهداف: شرح حالات الاستخدام التجاري لتنسيقات إخراج رمز المسح الضوئي في قائمة أفكار GSoD، تم ذكر تنسيقات إخراج رمز المسح الضوئي كفكرة مرجعية. ينفّذ هذا القسم الإجراء نفسه.
- ملاحظة: يتطلّب هذا الجزء مساعدة كبيرة من المرشد من حيث المدخلات حول حالات الاستخدام المختلفة لـ Scancode-Toolkit في الأنشطة التجارية والإشارات إليها.
[ 7. كيفية استخدام هذه النتائج من قِبل مشاريع AboutCode الأخرى لإجراء المزيد من التحليلات ]
- الهدف: سيقدّم هذا القسم ملخّصًا أساسيًا حول كيفية استخدام نتائج المسح الضوئي التي يوفّرها scancode-toolkit في حالات مختلفة، وأدوات Aboutcode التي توفّر هذه الوظيفة.
- نظرة عامة أساسية:
- Scancode-Workbench يشرح هذا القسم كيفية عرض النتائج باستخدام تطبيق الكمبيوتر المكتبي، ويقدّم مؤشرات إلى مستندات Scancode-workbench للحصول على مزيد من الدعم بشأن ذلك. سأضيف المستندات المطلوبة إلى scancode-workbench إذا لزم الأمر.
- Deltacode الطريقة التي تستخدمها Deltacode في تحليل نتائج Scancode لتحديد الاختلافات على مستوى الملف بين قاعدتَي رموز.
[ 2. إعادة تنظيم بنية مستندات AboutCode ]
يتضمّن هذا الجزء مجموعة من التغييرات على مستندات Aboutcode
[ 1. نظام تحديد الإصدار ]
في [ 1. خيارات سطر الأوامر في Scancode-Toolkit -> 2. بدء بنية تحديد الإصدار] تم ذكر مشكلة تحديد إصدار خيارات سطر الأوامر. وينطبق الأمر نفسه على الأجزاء الأخرى من المستندات التي تحتوي على أوامر أو معلومات خاصة بالإصدارات، والتي قد تؤدي إلى حدوث التباس.
[ 2. وضع معايير وتجارب توثيق ]
تتضمّن المستندات حاليًا اختبارات لـ spinx-build (لإنشاء جميع الصفحات والتحقّق من أخطاء بنية Sphinx في كل مكان) والتحقّق من الروابط (للتحقّق من جميع الروابط المؤدية إلى صفحات ويب أخرى من المستندات) باستخدام ميزة "التكامل المستمر" من خلال Travis-CI. (تمت إضافته من قِبل في طلب السحب هذا #17 ) يتطلّب الآن المزيد من عمليات التحقّق من التدقيق اللغوي المحدّد في reStructured Text والمعايير الأخرى. يمكن تحقيق ذلك باستخدام restructuredtext-lint، ولكنّه يحتاج إلى المزيد من البحث وسيتم تنفيذه كجزء من مشروع GSoD.
[ 3. إضافة قسم "البدء" ]
سيكون هذا القسم بمثابة نقطة بداية للمستخدمين الجدد وسيحتوي على مجموعة من المستندات الأساسية والمهمة للبدء في استخدام مشاريع Aboutcode. سيتضمّن كل مشروع من مشاريع Aboutcode هذا القسم، بما في ذلك Scancode-Toolkit وScancode-Workbench وDeltacode وغيرها.
[ 4. إعادة الهيكلة وفقًا لوظائف المستند الأربع ]
المستندات الحالية غير منظَّمة بشكل صريح في وظائف المستندات الأربع: البرامج التعليمية، وأدلة الإرشادات، والمراجع، والتفسيرات. أقترح تنظيمها وفقًا لذلك، مع إضافة المزيد من المعلومات أو التفسيرات أو المؤشرات أو أي شيء آخر ضروري. وينطبق ذلك على جميع مشاريع AboutCode ومستنداتها. في ما يلي مثالان على إعادة هيكلة مستندات Scancode-Toolkit التي أقترحها وأريد تنفيذها في هذا المشروع. سيتم إجراء تغييرات مماثلة على بقية المستندات.
[ 5. إعادة هيكلة صفحة التطوير (Scancode-Toolkit) ]
يمكن إضافة المزيد من المعلومات حول الرمز/واجهات برمجة التطبيقات لتسهيل استخدامه من قِبل المطوّرين. يمكن أن تتضمّن روابط إلى [ 2. مناقشات تشرح القسم "مسح الرمز" ] أعلاه يربط هذا الإجراء شرح طريقة عمل عملية الفحص بالرمز الذي يستخدمه لإجراء عملية الفحص. كما تحتوي هذه المجلدات على أجزاء مختلفة من scancode-toolkit، يمكن توضيح استخدامها الفردي من خلال واجهات برمجة التطبيقات، بالإضافة إلى المناقشة حول طريقة عمل scancode.
- [ cluecode : plugins for scanning licenses, copyrights, urls, emails ]
- [ commoncode : helper classes and functions]
- [ extractcode : extracts different archive formats ]
- [ formattedcode : تنسيق الإخراج لتنسيقات ملفات الإخراج المختلفة ]
- [ licensedcode : licence detection code ]
- [ packagedcode : parsing various package formats ]
- [ plugincode : classes for the plugins architecture ]
- [ summarycode : يلخّص عمليات الفحص التي تم إجراؤها على التراخيص التي تم رصدها ]
- [ textcode : handles text parsing ]
- [ typecode : handles file type determinations ]
- [ scancode : CLI and API to scancode, the core part ]
سيحتوي هذا القسم الفرعي على معلومات تفصيلية/واجهات برمجة تطبيقات حول هذه الأجزاء من scancode-toolkit في أقسام فرعية فرعية وفقًا لذلك. ستتوفّر إرشادات التطوير في صفحة أخرى أو قسم آخر يتضمّن أقسامًا فرعية أصغر.
[ 6. إعادة هيكلة صفحة الأسئلة الشائعة (Scancode-Toolkit) ]
تحتوي صفحة الأسئلة الشائعة حاليًا على أسئلة يمكن الإجابة عنها بشكل أفضل ويجب تنظيمها كمستندات منفصلة حول كيفية إجراء عمليات معيّنة، بالإضافة إلى دروس تعليمية ومستندات مرجعية.
- كيف تعمل أداة ScanCode؟ يتم الرجوع إلى هذه المشكلة في [ 2. مناقشات تشرح ميزة "مسح الرمز" ] وستكون قسمًا منفصلاً تمامًا يتضمّن المزيد من التفاصيل.
- كيفية إضافة قواعد ترخيص جديدة لتحسين عملية الرصد سبق أن ناقشنا هذه المشكلة في مقالة "تحسين مقالات الإرشادات الحالية"، وسيتم نقل المستندات إلى هناك.
- كيف يمكن إضافة قاعدة جديدة لرصد التراخيص؟ يمكن تحويل هذا إلى منشور آخر بعنوان "كيفية" بشكل منفصل وتوضيحه بشكل أكبر.
- كيفية البدء في التطوير تتوفّر حاليًا صفحة تطوير منفصلة، وتتداخل المعلومات الواردة فيها بشكل كبير. سبق أن ناقشنا إعادة هيكلة صفحة التطوير أعلاه.
- خطوات إنشاء إصدار جديد يمكن تحويل هذا المحتوى إلى مقالة منفصلة بعنوان "كيفية إنشاء إصدار جديد".
- يمكنك العثور على المزيد من الأسئلة الشائعة التي تجيب عن أسئلة عامة حول المشروع ولا تندرج ضمن فئتَي "كيفية التنفيذ" أو "برنامج تعليمي".