پروژه AboutCode
با مجموعه‌ها، منظم بمانید
ذخیره و طبقه‌بندی محتوا براساس اولویت‌های شما.
این صفحه حاوی جزئیات یک پروژه نگارش فنی است که برای فصل اسناد Google پذیرفته شده است.
خلاصه پروژه
- سازمان منبع باز:
- درباره کد
- نویسنده فنی:
- ayansinha
- نام پروژه:
- مرجع گزینه های خط فرمان در scancode-toolkit و سازماندهی مجدد ساختار اسناد AboutCode در aboutcode.readthedocs.io
- طول پروژه:
- طول استاندارد (3 ماه)
شرح پروژه
Scancode-Toolkit دارای مجموعه ای از گزینه های Command Line برای سفارشی کردن نحوه انجام اسکن، فرمت خروجی و چندین گزینه دیگر مانند افزونه های پس از اسکن است. این گزینه ها در حال حاضر مستندات مناسبی برای توضیح آنها ندارند و فقط از طریق پرچم "--help" یا "-h" در دسترس هستند. هدف این پروژه تهیه مستندات کامل است که توضیح می دهد:
[1. تمام گزینه های موجود از طریق خط فرمان]
- هدف: فهرستی جامع از تمام گزینه های ممکن از طریق خط فرمان.
- نمای کلی اولیه: ابتدا، گزینه های اسکن پیش فرض با مثالی از خروجی مورد بحث قرار می گیرد. یک تصویر/توضیح کوتاه در مورد نحوه انجام اسکن.
از این پس، این رفتار پیش‌فرض به عنوان مرجعی عمل می‌کند که چگونه گزینه‌های دیگر اسکن و خروجی را تغییر می‌دهند.
اینها باید به تفصیل مورد بحث قرار گیرند و حاوی اطلاعات زیر هستند همانطور که در بخش های بعدی ذکر شد.
[ 2. راه اندازی ساختار نسخه ]
- هدف: راه‌اندازی یک سیستم نسخه‌سازی برای حفظ صحیح گزینه‌های انتشار متقابل/API و تغییرات اسناد.
- مشکل: در حال حاضر اسناد موجود در ویکی و صفحات ReadTheDocs برای نسخه های قدیمی تر هستند و نیاز به بازسازی اساسی دارند.
- نمای کلی: بخش‌هایی از Scancode-Toolkit که به‌روزرسانی شده‌اند/می‌توانند در نسخه به‌روزرسانی شوند:
- گزینه های خط فرمان
- API ها
- اسناد (برای شروع) گزینه‌های خط فرمان و APIها در نسخه‌ها و نسخه‌ها تغییر می‌کنند و مستندات نیز باید دنبال شوند، در غیر این صورت سردرگمی عظیمی برای کاربران ایجاد می‌کند. ابزار خط فرمان [ --help ] در حال حاضر برای هرگونه تغییر در گزینه ها به روز شده است و می تواند برای تکرار نسخه سازی در اسناد استفاده شود.
[ 3. چگونه می توان از این گزینه ها در موارد مختلف استفاده کرد]
- هدف: این بخش خلاصه‌ای اساسی از نحوه استفاده از نتایج اسکن scancode-toolkit در علل مختلف و گزینه‌های Scancode-Toolkit که چنین عملکردی را ارائه می‌دهند، ارائه می‌کند.
- نمای کلی پایه: این بخش نمونه‌های مختلف سناریوهای مورد استفاده و گزینه‌هایی را که در آن سناریوها توصیه می‌شوند، ارائه می‌دهد.
- توجه: این بخش از نظر ورودی ها و اشاره به موارد استفاده مختلف از Scancode-Toolkit به کمک قابل توجهی از مربی نیاز دارد.
[ 4. آنچه که این گزینه ها در اسکن و خروجی تغییر می دهند ]
- هدف: این بخش خلاصه ای اساسی از نحوه استفاده از نتایج اسکن scancode-toolkit در علل مختلف و ابزار Aboutcode که چنین عملکردی را ارائه می دهند، ارائه می دهد.
- نمای کلی اولیه: گزینه ها رفتار نحوه انجام اسکن را تغییر می دهند. یک مورد پیش‌فرض اولیه در بخش اصلی [1. همه گزینه‌های موجود از طریق خط فرمان] نشان داده می‌شود و این بخش تغییراتی را که همه گزینه‌ها در این سناریوی پیش‌فرض ایجاد می‌کنند مقایسه می‌کند.
- هدف: این بخش خلاصه ای اساسی از نحوه استفاده از نتایج اسکن scancode-toolkit در علل مختلف و ابزار Aboutcode که چنین عملکردی را ارائه می دهند، ارائه می دهد.
- نمای کلی اولیه: Scancode-Tool دارای پرچم هایی برای تعیین فرمت های خروجی مختلف است که در آنها نتایج اسکن تولید می شود. اینها هستند -
این قسمت خواهد شد - فرمت های خروجی را با جزئیات توضیح دهید
- در فرمت های خروجی مثال بزنید
- پیوندهای دیگر مربوط به فرمت خروجی و استفاده از آن را ارائه دهید
- نحوه ذخیره نتایج اسکن در فایل های خروجی این همچنین به نحوه تولید این فرمت‌های مختلف پیوند می‌دهد که در [2. بحث‌هایی که اسکن کد را توضیح می‌دهند] توضیح داده خواهد شد.
- اهداف: موارد استفاده تجاری فرمت‌های خروجی Scancode را توضیح دهید در فهرست ایده‌های GSoD، فرمت‌های خروجی Scancode به عنوان یک ایده مرجع ذکر شده است. این بخش نیز همین کار را انجام می دهد.
- توجه: این بخش از نظر ورودی ها و اشاره به موارد مختلف استفاده تجاری از Scancode-Toolkit به کمک قابل توجهی از مربی نیاز دارد.
[ 7. نحوه استفاده از این خروجی ها توسط سایر پروژه های AboutCode برای تجزیه و تحلیل بیشتر ]
- هدف: این بخش خلاصه ای اساسی از نحوه استفاده از نتایج اسکن scancode-toolkit در علل مختلف و ابزار Aboutcode که چنین عملکردی را ارائه می دهند، ارائه می دهد.
- نمای کلی:
- Scancode-Workbench این بخش تجسم نتایج را با برنامه دسکتاپ و اشاره گرها به اسناد scancode-workbench برای پشتیبانی بیشتر در مورد آن توضیح می دهد. در صورت لزوم، اسناد مورد نیاز را به scancode-workbench اضافه می کند.
- Deltacode چگونه نتایج اسکن کد توسط Deltacode برای تعیین تفاوت سطح فایل بین دو پایگاه کد گرفته می شود.
[ 2. سازماندهی مجدد ساختار مستندات AboutCode ]
این بخش شامل مجموعه ای از تغییرات در مستندات درباره کد است
[ 1. سیستم نسخه سازی ]
در [ 1. Scancode-Toolkit Command Line Options -> 2. Initiate Versioning Structure] موضوع نسخه سازی گزینه های Command Line ذکر شده است. همین امر برای سایر بخش‌های اسناد نیز ضروری است که حاوی دستورات/اطلاعات خاص نسخه هستند که در غیر این صورت باعث سردرگمی می‌شوند.
[ 2. تنظیم استانداردها و آزمایشات مستندات ]
این اسناد قبلاً دارای آزمایشاتی برای spinx-build هستند (همه صفحات را می سازد و خطاهای نحوی Sphinx را در سراسر آن بررسی می کند) و بررسی پیوند (تمام پیوندهای سایر صفحات وب را از اسناد بررسی می کند) با یکپارچه سازی مداوم از طریق Travis-CI. (که توسط من در این درخواست کشش شماره 17 اضافه شده است) اکنون به بررسی های بیشتری برای پرده های خاص در متن بازسازی شده و سایر استانداردها نیاز دارد. این را می توان با restructuredtext-lint به دست آورد، اما به تحقیقات بیشتری نیاز دارد و به عنوان بخشی از پروژه GSoD من انجام خواهد شد.
[ 3. افزودن بخش «شروع به کار» ]
این به عنوان یک بخش شروع برای تازه واردان عمل می کند و حاوی مجموعه ای از اساسی ترین و مهم ترین اسناد برای شروع با پروژه های Aboutcode است. هر پروژه Aboutcode دارای این بخش از جمله Scancode-Toolkit، Scancode-Workbench، Deltacode و موارد دیگر خواهد بود.
[ 4. بازسازی با توجه به 4 تابع سند ]
مستندات موجود به صراحت در 4 تابع سند - آموزش ها، نحوه انجام کارها، مرجع و توضیحات ساختاربندی نشده است. من پیشنهاد می‌کنم آنها را بر این اساس ساختاربندی کنیم و اطلاعات/توضیحات/اشاره‌های بیشتری را هرچه لازم است اضافه کنیم. این برای تمام پروژه های AboutCode و مستندات آنها صادق است. در زیر دو نمونه از بازسازی اسناد Scancode-Toolkit وجود دارد که پیشنهاد کرده‌ام و می‌خواهم در این پروژه ادامه دهم. تغییرات مشابهی در بقیه اسناد انجام خواهد شد.
[ 5. بازسازی صفحه توسعه (Scancode-Toolkit) ]
اطلاعات بیشتر در مورد کد/APIها می‌تواند اضافه شود تا آن را برای توسعه‌دهندگان دوست‌دارتر کند. می‌توان پیوندهایی به بخش [ 2. بحث در مورد توضیح اسکن کد] در بالا وجود داشت. این توضیح نحوه عملکرد اسکن را به کدی که برای انجام اسکن استفاده می کند پیوند می دهد. مانند این پوشه ها شامل بخش های مختلف Scancode-Toolkit هستند، استفاده فردی آنها را می توان با API ها همراه با بحث در مورد نحوه عملکرد اسکن کد توضیح داد.
- [کلیدکد: افزونه‌هایی برای اسکن مجوزها، حق چاپ، آدرس‌های اینترنتی، ایمیل‌ها]
- [کد مشترک: کلاس های کمکی و توابع]
- [extractcode: استخراج فرمت های مختلف آرشیو]
- [formtedcode: قالب‌بندی خروجی برای فرمت‌های مختلف فایل خروجی]
- [کد مجوز: کد شناسایی مجوز]
- [packedcode: تجزیه فرمت های مختلف بسته]
- [ کد پلاگین : کلاس های معماری پلاگین ها ]
- [خلاصه کد: اسکن در مجوزهای شناسایی شده را خلاصه می کند]
- [ textcode : تجزیه متن را کنترل می کند ]
- [نوع کد: تعیین نوع فایل را انجام می دهد]
- [اسکن کد: CLI و API برای اسکن کد، بخش اصلی]
این بخش فرعی حاوی اطلاعات/APIهای دقیق در مورد این بخش‌های scancode-toolkit در زیربخش‌ها خواهد بود. دستورالعمل های توسعه در صفحه دیگری یا بخش دیگری با بخش های فرعی کوچکتر وجود دارد.
[ 6. بازسازی صفحه پرسش‌های متداول (Scancode-Toolkit)]
صفحه پرسش‌های متداول در حال حاضر دارای سؤالاتی است که می‌توان به آنها پاسخ بهتری داد و باید به‌صورت مجزای نحوه انجام، آموزش‌ها و اسناد مرجع به طور جداگانه ساختار داده شود.
- ScanCode چگونه کار می کند؟ این موضوع در [2. بحث در مورد توضیح اسکن کد] ارجاع شده است و یک بخش کاملاً جداگانه در جزئیات بسیار بیشتر خواهد بود.
- چگونه قوانین مجوز جدید را برای تشخیص پیشرفته اضافه کنیم؟ این موضوع قبلاً در بهبود روش‌های موجود بحث شده است، اسناد به آنجا منتقل خواهند شد.
- چگونه یک قانون جدید تشخیص مجوز اضافه کنیم؟ این را می توان به صورت جداگانه در یک پست دیگر "چگونه به" تبدیل کرد و می توان در مورد آن توضیح داد.
- چگونه با توسعه شروع کنیم؟ در حال حاضر یک صفحه توسعه جداگانه وجود دارد و اطلاعات بسیار با هم تداخل دارند. بازسازی صفحه توسعه قبلاً در بالا مورد بحث قرار گرفته است.
- مراحل کاهش نسخه جدید این می تواند به یک "چگونه نسخه جدید را برش دهیم" جداگانه تبدیل شود.
- سؤالات متداول بیشتری را بیابید که به سؤالات عمومی در مورد پروژه پاسخ می دهند و در دسته بندی «چگونه»/«آموزش» قرار نمی گیرند.
محتوای این صفحه تحت مجوز Creative Commons Attribution 4.0 License است، مگر غیر از این ذکر شده باشد. برای اطلاع از جزئیات، به خطمشیهای سایت Google Developers مراجعه کنید. جاوا علامت تجاری ثبتشده 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."]]
