مشروع لمحة عن الرمز

تحتوي هذه الصفحة على تفاصيل مشروع كتابة تقنيّة تم قبوله في موسم المستندات من Google.

ملخص المشروع

المؤسسة المفتوحة المصدر:
AboutCode
الكاتب التقني:
أيانسينا
اسم المشروع:
مرجع لخيارات سطر الأوامر في Sccode- Toolkit وإعادة تنظيم بنية وثائقAboutCode على aboutcode.readthedocs.io
مدة المشروع:
المدة العادية (3 أشهر)

وصف المشروع

[ 1- خيارات سطر الأوامر الخاصة بفحص رمز الأدوات ]

يتضمن Scancode-Toolkit مجموعة من خيارات "سطر الأوامر" لتخصيص كيفية إجراء الفحص وتنسيق الإخراج والعديد من الخيارات الأخرى مثل المكوّنات الإضافية التي تلي الفحص. لا تشمل هذه الخيارات حاليًا المستندات المناسبة لشرحها ولا تتوفّر إلّا من خلال العلامة " --help" أو " -h". يهدف هذا المشروع إلى تقديم وثائق كاملة توضح ما يلي:

[ 1- جميع الخيارات المتاحة من خلال سطر الأوامر ]

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

[ 2- بدء بنية تحديد الإصدارات ]

  • الهدف: بدء نظام تعيين الإصدارات للحفاظ على خيارات الإصدار المتقاطع/واجهة برمجة التطبيقات والتغييرات التوثيقية بشكل صحيح.
  • المشكلة: في الوقت الحالي، الوثائق الموجودة في موقع wiki وصفحات ReadThe Docs مخصصة للإصدارات القديمة وتحتاج إلى إعادة هيكلة كبيرة.
  • نظرة عامة أساسية: تتضمن أجزاء مجموعة أدوات المسح الضوئي التي تم تحديثها/يمكن تحديثها في الإصدار
  • خيارات سطر الأوامر
  • واجهات برمجة التطبيقات
  • التوثيق (قيد البدء) يتم تغيير خيارات سطر الأوامر وواجهات برمجة التطبيقات في الإصدارات والإصدارات، ويجب أيضًا اتباع الوثائق أيضًا، وإلا فقد ينشأ عنها التباس كبير للمستخدمين. سبق أن تم تحديث أداة سطر الأوامر [ --help ] لتتيح أي تغييرات في الخيارات، ويمكن استخدامها لتكرار تحديد الإصدارات في الوثائق.

[ 3- كيفية استخدام هذه الخيارات في حالات مختلفة ]

  • الهدف: سيقدم هذا القسم ملخصًا أساسيًا حول كيفية استخدام نتائج الفحص لمجموعة أدوات مسح الرمز ضوئيًا لأسباب مختلفة وخيارات Scancode-Toolkit التي توفر هذه الوظيفة.
  • نظرة عامة أساسية: يقدم هذا القسم أمثلة على سيناريو حالة استخدام مختلفة والخيارات المقترحة في تلك السيناريوهات.
  • ملاحظة: يتطلب هذا الجزء مساعدة مهمة من الموجه من حيث المدخلات والمؤشرات حول حالات الاستخدام المختلفة لـ Scancode-Toolkit.

[ 4- ما الذي تتغير فيه هذه الخيارات في المسح والإخراج ]

  • الهدف: سيقدم هذا القسم ملخصًا أساسيًا حول كيفية استخدام نتائج المسح الضوئي لمجموعة أدوات رمز المسح الضوئي في أسباب مختلفة، إلى جانب أدوات "نبذة عن الترميز" التي توفر هذه الوظائف.
  • نظرة عامة أساسية: تغيّر الخيارات سلوك طريقة إجراء الفحص. سيتم توضيح الحالة الافتراضية الأساسية في القسم الأول [ 1. جميع الخيارات المتاحة من خلال سطر الأوامر ] وسيقارن هذا القسم التغييرات التي تجلبها جميع الخيارات إلى هذا السيناريو الافتراضي.

[ 5- تنسيقات الإخراج وأمثلةها ]

  • الهدف: سيقدم هذا القسم ملخصًا أساسيًا حول كيفية استخدام نتائج المسح الضوئي لمجموعة أدوات رمز المسح الضوئي في أسباب مختلفة، إلى جانب أدوات "نبذة عن الترميز" التي توفر هذه الوظائف.
  • نظرة عامة أساسية: تحتوي أداة Scancode-Tool على علامات لتحديد تنسيقات الإخراج المختلفة التي سيتم إنشاء نتائج الفحص بها. وهي -
    سينشئ هذا الجزء
  • واشرح بالتفصيل تنسيقات الإخراج
  • تقديم أمثلة حول تنسيقات الإخراج
  • بإعطاء روابط أخرى متوافقة مع تنسيق الإخراج واستخدامه
  • كيفية تخزين نتائج الفحص في ملفات الإخراج. يؤدي هذا أيضًا إلى كيفية إنشاء هذه التنسيقات المختلفة، والتي سيتم توضيحها في [ 2. مناقشات تشرح مسح التعليمة البرمجية ].

[ 6- استخدام الأعمال لتنسيقات إخراج رمز المسح الضوئي ]

  • الأهداف: شرح حالات استخدام الأعمال لتنسيقات إخراج Scancode في قائمة أفكار GSoD، تتم الإشارة إلى تنسيقات ناتج مسح الرمز ضوئيًا كفكرة مرجعية. وينطبق هذا القسم أيضًا.
  • ملاحظة: يتطلب هذا الجزء مساعدة كبيرة من الموجه من حيث المدخلات والمؤشرات حول حالات استخدام الأعمال المختلفة لـ Scancode-Toolkit.

[ 7- كيفية استخدام هذه المخرجات في مشاريعAboutCode الأخرى لمزيد من التحليل ]

  • الهدف: سيقدم هذا القسم ملخصًا أساسيًا حول كيفية استخدام نتائج المسح الضوئي لمجموعة أدوات رمز المسح الضوئي في أسباب مختلفة، إلى جانب أدوات "نبذة عن الترميز" التي توفر هذه الوظائف.
  • نظرة عامة أساسية:
  • Scancode-Workbench يشرح هذا الجزء تمثيلاً بصريًا للنتائج باستخدام تطبيق سطح المكتب ويقدّم توجيهات حول وثائق جدول عمل رمز المسح الضوئي للحصول على مزيد من الدعم في الوقت نفسه. ستتم إضافة المستندات المطلوبة إلى Sccode-workbench إذا لزم الأمر.
  • Deltacode كيف يتم أخذ نتائج رمز المسح الضوئي بواسطة Deltacode لتحديد الاختلافات في مستوى الملف بين قاعدتَي رموز.

[ 2- إعادة تنظيم بنية وثائق aboutCode ]

يتضمن هذا الجزء مضيفًا من التغييرات في وثائق "Aboutcode" (حول وثائق)

[ 1- نظام تحديد الإصدارات ]

في [ 1. خيارات سطر الأوامر Scancode-Toolkits -> 2. بدء هيكل تحديد الإصدارات] تم ذكر مشكلة تحديد إصدارات خيارات سطر الأوامر. وهذا أمر ضروري لأجزاء أخرى من الوثائق أيضًا تحتوي على أوامر/معلومات خاصة بالإصدار والتي من شأنها أن تسبب التباسًا بخلاف ذلك.

[ 2- وضع معايير واختبارات التوثيق ]

تحتوي الوثائق بالفعل على اختبارات بشأن إنشاء Spinx-build (ينشئ جميع الصفحات ويتحقق من أخطاء بنية Sphinx طوال الوقت) وفحص الروابط (يتحقق من جميع الروابط إلى صفحات الويب الأخرى من الوثائق) باستخدام الدمج المستمر من خلال Travis-CI. (تمت إضافتها بواسطتي في طلب السحب رقم 17 هذا) تحتاج الآن إلى مزيد من عمليات التحقق من المحتوى غير الصحيح المحدد في النص المُعاد تنظيمه والمعايير الأخرى. ويمكن تحقيق ذلك باستخدام أداة لين النص المُعاد هيكلها، ولكن يحتاج إلى مزيد من الأبحاث وسيتم إجراؤه كجزء من مشروع GSoD الخاص بي.

[ 3- إضافة قسم "البدء" ]

سيكون هذا بمثابة قسم بداية للمستخدمين الجدد وسيحتوي على مجموعة من المستندات الأساسية والأكثر أهمية لبدء مشاريعAboutcode (نبذة عني). سيحتوي كل مشروع حول الترميز على هذا القسم، بما في ذلك Scancode-Toolkit وScancode-Workbench وdeltacode وغيرها.

[ 4- إعادة الهيكلة وفقًا لدوال المستند الأربع ]

لم يتم تنظيم الوثائق الحالية بشكل صريح في وظائف الوثيقة الأربع: البرامج التعليمية، وكيفية التنفيذ، والمراجع، والتفسيرات. لذا أقترح تنظيمها وفقًا لذلك، وإضافة المزيد من المعلومات/التفسيرات/المؤشرات حسب الضرورة. وهذا ينطبق على جميع مشاريعAboutCode ووثائقها. فيما يلي مثالان على إعادة هيكلة وثائق Scancode-Toolkit التي أقترحها وأودّ متابعة هذا المشروع فيها. سيتم إجراء تغييرات مماثلة على باقي الوثائق.

[ 5- إعادة هيكلة صفحة التطوير (Scancode-Toolkit) ]

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

  • [ cluecode : مكونات إضافية لفحص التراخيص وحقوق الطبع والنشر وعناوين URL ورسائل البريد الإلكتروني ]
  • [ commoncode : الفئات والدوال المساعدة]
  • [ استخراجcode : يستخرج تنسيقات أرشيف مختلفة ]
  • [ رمز منسق : تنسيق الناتج لتنسيقات ملفات الإخراج المختلفة ]
  • [ رمز الترخيص : رمز اكتشاف الترخيص ]
  • [ packagedcode : تحليل تنسيقات حزمة مختلفة ]
  • [ رمز المكوّن الإضافي : فئات لبنية المكوّنات الإضافية ]
  • [ الرمز التلخيصي : يلخص عملية الفحص في التراخيص التي تم اكتشافها ]
  • [ الرمز النصي : يعالج تحليل النص ]
  • [ typecode : تتعامل مع تحديدات نوع الملف ]
  • [ مسح الرمز ضوئيًا : واجهة سطر الأوامر (CLI) وواجهة برمجة التطبيقات لمسح الرمز ضوئيًا، الجزء الأساسي ]

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

[ 6- إعادة هيكلة صفحة الأسئلة الشائعة (Scancode-Toolkit) ]

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

  • كيف تعمل خدمة ScanCode؟ تمت الإشارة إلى هذه المشكلة في [ 2. مناقشات تشرح التعليمة البرمجية ] وستكون قسمًا منفصلاً تمامًا بمزيد من التفاصيل.
  • كيف يمكن إضافة قواعد ترخيص جديدة للرصد المحسّن؟ سبق أن تمت مناقشة هذه المشكلة في قسم "تحسين طريقة التنفيذ" الحالية، وسيتم نقل المستندات إليها.
  • كيف يمكن إضافة قاعدة جديدة لاكتشاف ترخيص؟ يمكن إنشاء هذا في مشاركة "كيفية" أخرى بشكل منفصل ويمكن تفصيله.
  • كيف تبدأ في التطوير؟ توجد بالفعل صفحة تطوير منفصلة، وتتداخل المعلومات كثيرًا. سبق أن ناقشنا سابقًا عملية إعادة هيكلة صفحة التطوير.
  • خطوات نسخ إصدار جديد يمكن تحويله إلى مقالة منفصلة بعنوان "كيفية تعديل إصدار جديد".
  • ابحث عن المزيد من أسئلة الأسئلة الشائعة التي تجيب عن الأسئلة العامة حول المشروع ولا تندرج ضمن فئات "How To"/"البرنامج التعليمي".