مشروع لمحة عن الرمز
تنظيم صفحاتك في مجموعات
يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.
تحتوي هذه الصفحة على تفاصيل مشروع كتابة فنية تم قبوله في
"موسم مستندات Google".
ملخّص المشروع
- مؤسسة مفتوحة المصدر:
- AboutCode
- الكاتب الفني:
- ayansinha
- اسم المشروع:
- مرجع لخيارات سطر الأوامر في helpcode- Toolkit وأعِد تنظيم بنية مستنداتAboutCode على الرابط aboutcode.readthedocs.io.
- مدة المشروع:
- المدة العادية (3 أشهر)
وصف المشروع
يشتمل Scancode-Toolkit على مجموعة من خيارات سطر الأوامر لتخصيص كيفية إجراء الفحص وتنسيق الإخراج والعديد من الخيارات الأخرى مثل المكوّنات الإضافية لما بعد الفحص. لا تتوفّر حاليًا مستندات توضيحية لهذه الخيارات، ولا يمكن استخدامها إلا من خلال العلامة "--help" أو "-h". يهدف هذا المشروع إلى إنشاء مستندات كاملة توضّح ما يلي:
[ 1. جميع الخيارات المتاحة من خلال سطر الأوامر ]
- الهدف: قائمة شاملة بكل الخيارات الممكنة من خلال سطر الأوامر
- نظرة عامة أساسية: أولاً، تتم مناقشة خيارات المسح التلقائية، مع تقديم مثال على الإخراج. رسم بياني/وصف موجز لكيفية إجراء عملية المسح
من الآن فصاعدًا، سيُستخدَم هذا السلوك التلقائي كمرجع لكيفية تغيير الخيارات الأخرى للفحص والنتيجة.
ستتم مناقشة هذه المسائل بالتفصيل وستتضمّن المعلومات التالية كما هو موضّح في الأقسام التالية.
[ 2. بدء بنية تحديد الإصدارات ]
- الهدف: بدء نظام تحديد الإصدارات للحفاظ على التغييرات في خيارات/واجهات برمجة التطبيقات والمستندات على مستوى جميع الإصدارات
- المشكلة: في الوقت الحالي الوثائق الموجودة في موقع wiki وصفحات ReadThe Docs خاصة بالإصدارات القديمة وتحتاج إلى إعادة هيكلة كبيرة.
- نظرة عامة أساسية:
في ما يلي أجزاء مجموعة أدوات رموز الاستيلاء التي تم تعديلها/يمكن تعديلها في الإصدار:
- خيارات سطر الأوامر
- واجهات برمجة التطبيقات
- المستندات (سيتم بدء العمل عليها)
يتم تغيير خيارات سطر الأوامر وواجهات برمجة التطبيقات في الإصدارات، ويجب أن تتّبع المستندات ذلك أيضًا، وإلا سيؤدي ذلك إلى حدوث ارتباك كبير لدى المستخدمين. تم تعديل الأداة التي تعمل على سطر الأوامر [ --help ] لأي تغييرات في الخيارات، ويمكن استخدامها لتكرار نظام الإصدار في المستندات.
[ 3. كيفية استخدام هذه الخيارات في حالات مختلفة ]
- الهدف: سيقدّم هذا القسم ملخّصًا أساسيًا لكيفية استخدام نتائج المسح الضوئي لأداة Scancode-Toolkit في أسباب مختلفة وخيارات Scancode-Toolkit التي توفّر هذه الوظيفة.
- نظرة عامة أساسية: يقدّم هذا القسم أمثلة مختلفة لسيناريو حالة الاستخدام والخيارات المقترَحة في تلك السيناريوهات.
- ملاحظة: يتطلب هذا الجزء مساعدة كبيرة من المرشد من حيث المدخلات حول حالات الاستخدام المختلفة لأداة Scancode-Toolkit وتوجيهات بشأنها.
[ 4- ما الذي تغيره هذه الخيارات في الفحص والإخراج ]
- الهدف: سيقدّم هذا القسم ملخّصًا أساسيًا لكيفية استخدام نتائج المسح الضوئي من أداة scancode-toolkit في أسباب مختلفة، وأدوات Aboutcode التي توفّر هذه الوظيفة.
- نظرة عامة أساسية: تعمل الخيارات على تغيير سلوك طريقة إجراء عملية المسح.
سيتم توضيح حالة تلقائية أساسية في القسم الرئيسي [ 1. جميع الخيارات المتاحة من خلال سطر الأوامر ] سيقارن هذا القسم التغييرات التي تحقّقها جميع الخيارات في هذا السيناريو التلقائي.
- الهدف: سيقدّم هذا القسم ملخّصًا أساسيًا لكيفية استخدام نتائج المسح الضوئي من أداة scancode-toolkit في أسباب مختلفة، وأدوات Aboutcode التي توفّر هذه الوظيفة.
- نظرة عامة أساسية: تحتوي أداة Scancode على علامات لتحديد تنسيقات الإخراج المختلفة التي سيتم إنشاء نتائج المسح فيها. وهي:
سيتناول هذا الجزء
- شرح تنسيقات الإخراج بالتفصيل
- تقديم أمثلة على تنسيقات النتائج
- منح روابط أخرى تتوافق مع تنسيق الإخراج واستخدامه
- كيفية تخزين نتائج المسح في ملفات الإخراج
يرتبط هذا أيضًا بطريقة إنشاء هذه التنسيقات المختلفة، والتي سيتم شرحها في [ 2. مناقشات تشرح مسح الرموز ].
- الأهداف: توضيح حالات استخدام تنسيقات نتائج رموز الاستيلاء على البيانات في مجال الأعمال
في قائمة أفكار 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?
وهناك بالفعل صفحة تطوير منفصلة وتتداخل المعلومات إلى حد كبير. سبق أن تمت مناقشة إعادة هيكلة صفحة التطوير أعلاه.
- خطوات إنشاء إصدار جديد
يمكن تحويل هذه الخطوات إلى مقالة منفصلة بعنوان "كيفية إنشاء إصدار جديد".
- ابحث عن المزيد من الأسئلة الشائعة التي تجيب عن أسئلة عامة حول المشروع ولا تندرج ضمن فئات "الدليل التعليمي" أو "كيفية".
إنّ محتوى هذه الصفحة مرخّص بموجب ترخيص Creative Commons Attribution 4.0 ما لم يُنصّ على خلاف ذلك. للاطّلاع على التفاصيل، يُرجى مراجعة سياسات موقع Google Developers. إنّ Java هي علامة تجارية مسجّلة لشركة Oracle و/أو شركائها التابعين.
تاريخ التعديل الأخير: 2025-07-25 (حسب التوقيت العالمي المتفَّق عليه)
[null,null,["تاريخ التعديل الأخير: 2025-07-25 (حسب التوقيت العالمي المتفَّق عليه)"],[[["\u003cp\u003eThis project focuses on enhancing the documentation for the Scancode-Toolkit, an open-source tool by AboutCode used for code analysis.\u003c/p\u003e\n"],["\u003cp\u003eThe project aims to create comprehensive documentation for Scancode-Toolkit's command line options, including their use cases and impact on scan results.\u003c/p\u003e\n"],["\u003cp\u003eA key aspect of the project involves restructuring AboutCode's documentation to improve organization, introduce versioning, and establish documentation standards.\u003c/p\u003e\n"],["\u003cp\u003eThe project also includes a section on business use cases of Scancode output formats and how other AboutCode projects utilize Scancode's results.\u003c/p\u003e\n"],["\u003cp\u003eThis initiative aims to make the documentation more user-friendly, accessible and comprehensive for both newcomers and experienced developers.\u003c/p\u003e\n"]]],["This technical writing project aims to enhance the documentation for AboutCode's scancode-toolkit. Key actions include: documenting all command-line options, initiating a versioning system for options, APIs, and documentation, illustrating use cases and output format details, and explaining business applications. Additionally, it involves reorganizing AboutCode documentation by implementing a versioning system, adding a \"Getting Started\" section, restructuring content according to document functions, enhancing the development page, and restructuring the FAQ page.\n"],null,["# AboutCode project\n\nThis page contains the details of a technical writing project accepted for\nGoogle Season of Docs.\n\n### Project summary\n\nOpen source organization:\n: AboutCode\n\nTechnical writer:\n: ayansinha\n\nProject name:\n: Reference for Command Line Options in scancode-toolkit and Reorganize the structure of AboutCode documentation at aboutcode.readthedocs.io\n\nProject length:\n: Standard length (3 months)\n\n### Project description\n\n\\[ 1. Scancode-Toolkit Command Line Options \\]\n----------------------------------------------\n\nScancode-Toolkit has a host of Command Line options to customize how the scan is performed, the output format and several other options like post-scan plugins. These options currently don't have proper documentation to explain them and are only available through the \"--help\" or \"-h\" flag. This project aims to make complete documentation that explains:\n\n### \\[ 1. All the Options available through Command Line \\]\n\n- Goal: An exhaustive list of all possible options through the command line.\n- Basic Overview: First, the default scan options are discussed, with an example of the output. A short graphic/description on how the scan is performed. \n Hereafter, this default behavior acts as a reference to how the other options change the scan and the output. \n These are to be discussed in detail and will contain the following information as mentioned in the next sections.\n\n### \\[ 2. Initiate Versioning Structure \\]\n\n- Goal: Initiate a versioning system to properly maintain cross-release options/API and documentation changes.\n- Problem: Presently the documentation in the wiki and the ReadTheDocs pages are for older releases and needs major restructuring.\n- Basic Overview: The parts of the scancode-toolkit that have been updated/could be updated in version are\n- Command Line Options\n- APIs\n- Documentation (To be initiated) The command line options and the APIs are changed in versions and releases, and the documentation also has to follow, or it will create massive confusion for the users. The command line utility \\[ --help \\] already is updated for any changes in options and could be used to replicate the versioning in the documentation.\n\n### \\[ 3. How these Options can be used in different cases \\]\n\n- Goal: This section will provide a basic summary of how the scan results of scancode-toolkit can be used in different causes and the Scancode-Toolkit options that provide such functionality.\n- Basic Overview: This section gives different use case scenario examples and what options are recommended in those scenarios.\n- Note: This part requires significant help from the mentor in terms of inputs about and pointers to various use cases of Scancode-Toolkit.\n\n### \\[ 4. What these Options change in the Scan and the Output \\]\n\n- Goal: This section will provide a basic summary of how the scan results of scancode-toolkit can be used in different causes, and the Aboutcode tools that provide such functionality.\n- Basic Overview: The options change the behavior of how the scan is performed. A basic default case will be illustrated in the leading section \\[ 1. All the Options available through Command Line \\] and this section will compare the changes that all the options bring to this default scenario.\n\n### \\[ 5. Output Formats and their examples \\]\n\n- Goal: This section will provide a basic summary of how the scan results of scancode-toolkit can be used in different causes, and the Aboutcode tools that provide such functionality.\n- Basic Overview: Scancode-Tool has flags to specify different output formats in which the scan results will be generated. These are - \n This part will\n- explain in detail the output formats\n- give examples on the output formats\n- give other links corresponding to the output format and its use\n- how scan results are stored in the output files. This also links to How these different formats are generated, which will be explained in \\[ 2. Discussions explaining Code Scanning \\].\n\n### \\[ 6. Business Use of Scancode Output Formats \\]\n\n- Goals: Explain the Business Use cases of Scancode Output formats In the GSoD ideas list, Scancode Output Formats is mentioned as a reference idea. This section implements the same.\n- Note: This part requires significant help from the mentor in terms of inputs about and pointers to various business use cases of Scancode-Toolkit.\n\n### \\[ 7. How these outputs are used by other AboutCode projects for more analysis \\]\n\n- Goal: This section will provide a basic summary of how the scan results of scancode-toolkit can be used in different causes, and the Aboutcode tools that provide such functionality.\n- Basic Overview:\n- Scancode-Workbench This part explains visualizing results with the desktop app and pointers to scancode-workbench documentation for more support on the same. Will add required documentation to scancode-workbench if necessary.\n- Deltacode How scancode results are taken by Deltacode to determine file level differences between two codebases.\n\n\\[ 2. Reorganize the structure of AboutCode Documentation \\]\n------------------------------------------------------------\n\nThis part includes a host of changes to the Aboutcode Documentation\n\n### \\[ 1. Versioning system \\]\n\nIn \\[ 1. Scancode-Toolkit Command Line Options -\\\u003e 2. Initiate Versioning Structure\\] the issue of versioning the Command Line options are mentioned. The same is necessary for other parts of the documentation also which contain version specific commands/information that would otherwise create confusion.\n\n### \\[ 2. Setting Documentation Standards and Tests \\]\n\nThe documentation already has tests for spinx-build (builds all the pages and checks for Sphinx syntax errors throughout) and link check (Checks all the links to other webpages from the documentation) with Continuous Integration through Travis-CI. (Added by me in this Pull Request #17 )\nNow it needs more checks for specific linting in reStructured Text and other standards. This could be achieved with restructuredtext-lint but needs more research and will be done as a part of my GSoD project.\n\n### \\[ 3. Adding a \"Getting Started\" Section \\]\n\nThis will act as a starting section for newcomers and will contain a compilation of the most basic and important documents to get started with Aboutcode Projects.\nEvery Aboutcode Project will have this section including Scancode-Toolkit, Scancode-Workbench, Deltacode, and others.\n\n### \\[ 4. Restructuring According to the 4 Document Functions \\]\n\nThe existing Documentation isn't explicitly structured in the 4 document functions - Tutorials, How To's, Reference and Explanations. I propose to structure those accordingly, adding more information/explanations/pointers whatever necessary. This holds for all the AboutCode projects and their documentation. Below are two examples of the Scancode-Toolkit documentation restructuring I propose and would like to carry on in this project. Similar changes will be carried out on the rest of the documentation.\n\n### \\[ 5. Restructuring the Development Page (Scancode-Toolkit) \\]\n\nMore info on the Code/APIs could be added to make it more developer friendly.\nThere can be links to the \\[ 2. Discussions explaining the Code Scanning \\] section above. This links the explanation of how the scan works to the code it uses to perform the scan.\nLike these folders contain different parts of scancode-toolkit, their individual use can be elaborated with the APIs, in conjunction with the Discussion on how scancode works.\n\n- \\[ cluecode : plugins for scanning licenses, copyrights, urls, emails \\]\n- \\[ commoncode : helper classes and functions\\]\n- \\[ extractcode : extracts different archive formats \\]\n- \\[ formattedcode : output formatting for different output file formats \\]\n- \\[ licensedcode : licence detection code \\]\n- \\[ packagedcode : parsing various package formats \\]\n- \\[ plugincode : classes for the plugins architecture \\]\n- \\[ summarycode : summarizes scan on detected licenses \\]\n- \\[ textcode : handles text parsing \\]\n- \\[ typecode : handles file type determinations \\]\n- \\[ scancode : CLI and API to scancode, the core part \\]\n\nThis subsection will contain detailed information/APIs on these parts of scancode-toolkit in subsubsections accordingly.\nThe Development guidelines will be there in another page or another section having smaller subsections.\n\n### \\[ 6. Restructuring the FAQ page (Scancode-Toolkit) \\]\n\nThe FAQ page at present has questions which can be better answered and should be structured as separate How To's, Tutorials and Reference documents separately.\n\n- How does ScanCode work? This issue is referenced in \\[ 2. Discussions explaining the Code Scanning \\] and will be an entirely separate section in much more details.\n- How to Add New License Rules for Enhanced Detection? This issue is already discussed before in Improving the existing How-To's, documentation will be moved there.\n- How to add a new license detection rule? This could be made into another \"How To\" post separately and could be elaborated on.\n- How To get started with Development? There's already a separate development page and the information overlaps quite a lot. The restructuring of the development page has already been discussed above.\n- Steps to cut a new release This can be transformed into a separate \"How To Cut a new release\".\n- Find more FAQ questions which answer generic questions about the project and doesn't fall in the \"How To\"/\"Tutorial\" categories."]]
