aboutCode 项目
使用集合让一切井井有条
根据您的偏好保存内容并对其进行分类。
本页详细介绍了 Google 文档季收录的技术文案项目。
项目摘要
- 开源组织：
- AboutCode
- 技术文档工程师：
- 阿雅辛哈
- 项目名称：
- 在 aboutcode.readthedocs.io 上添加了 scancode-toolkit 命令行选项参考文档，并重组了 AboutCode 文档的结构
- 项目时长：
- 标准时长（3 个月）
Project description
Scancode-Toolkit 提供了一系列命令行选项，可用于自定义扫描方式、输出格式以及扫描后插件等其他选项。目前，这些选项还没有适当的文档来说明，只能通过“--help”或“-h”标志使用。此项目旨在制作完整的文档，说明以下内容：
[ 1. 通过命令行提供的所有选项 ]
- 目标：通过命令行列出所有可能的选项。
- 基本概览：首先，我们将介绍默认扫描选项，并附上输出示例。关于如何执行扫描的简短图形/说明。
以下部分将以此默认行为为参考，介绍其他选项如何更改扫描和输出。
我们将详细讨论这些内容，并包含以下信息，如以下部分所述。
[ 2. 启动版本控制结构 ]
- 目标：启动版本控制系统，以妥善维护跨版本选项/API 和文档更改。
- 问题：目前，维基中的文档和 ReadTheDocs 页面适用于旧版本，需要进行重大重构。
- 基本概览：扫码工具包在该版本中更新/可更新的部分如下：
- 命令行选项
- API
- 文档（待发起）
命令行选项和 API 会随着版本和发布版本而发生变化，文档也必须随之更新，否则会给用户造成极大的困惑。命令行实用程序 [ --help ] 已更新为反映选项中的任何更改，可用于复制文档中的版本控制。
[ 3. 如何在不同情况下使用这些选项 ]
- 目标：本部分将简要介绍 scancode-toolkit 的扫描结果如何用于不同的原因，以及提供此类功能的 Scancode-Toolkit 选项。
- 基本概览：本部分介绍了不同的使用情形示例，以及在这些情形中推荐的选项。
- 注意：在 Scancode-Toolkit 的各种用例方面，本部分需要导师提供大量帮助，包括提供相关输入和指针。
[ 4. 这些选项会如何更改扫描结果和输出结果
- 目标：本部分将简要介绍如何针对不同的原因使用 scancode-toolkit 的扫描结果，以及提供此类功能的“Aboutcode”工具。
- 基本概览：这些选项会更改执行扫描的方式。
前面部分将介绍一个基本默认用例 [ 1. 通过命令行提供的所有选项]，本部分将比较所有选项对此默认场景带来的更改。
- 目标：本部分将简要介绍如何针对不同的原因使用 scancode-toolkit 的扫描结果，以及提供此类功能的“Aboutcode”工具。
- 基本概述：Scancode-Tool 提供了一些标志，用于指定生成扫描结果时采用的不同输出格式。这些是 -
本部分将
- 详细说明了
- 提供输出格式的示例
- 提供与输出格式及其用途对应的其他链接
- 扫描结果在输出文件中的存储方式。此链接还会介绍如何生成这些不同的格式，具体内容将在 [ 2. 说明代码扫描的讨论]。
- 目标：说明扫码输出格式的业务用例
在 GSoD 想法列表中，扫码输出格式被提及为参考想法。本部分将实现相同的操作。
- 注意：在 Scancode-Toolkit 的各种业务用例方面，本部分需要导师提供大量帮助，包括提供相关信息和指针。
[ 7. 其他 AboutCode 项目如何使用这些输出进行进一步分析 ]
- 目标：本部分将简要介绍如何在不同情况下使用 scancode-toolkit 的扫描结果，以及提供此类功能的 Aboutcode 工具。
- 基本概述：
- Scancode-Workbench
本部分介绍如何使用桌面应用直观呈现结果，并提供了有关 scancode-workbench 文档的更多支持信息。如有必要，将向 scancode-workbench 添加所需文档。
- Deltacode
Deltacode 如何获取扫码结果，以确定两个代码库之间的文件级差异。
[ 2. 重新整理了“AboutCode”文档的结构
本部分介绍了对“关于代码”文档所做的一系列更改
[ 1. 版本控制系统 ]
在 [ 1. Scancode-Toolkit 命令行选项 -> 2. 启动版本控制结构] 提到了对命令行选项进行版本控制的问题。文档的其他部分也需要这样做，因为其中包含特定于版本的命令/信息，否则可能会造成混淆。
[ 2. 设置文档标准和测试 ]
该文档已通过 Travis-CI 持续集成，包含 spinx-build 测试（构建所有页面并检查整个过程中是否存在 Sphinx 语法错误）和链接检查（检查文档中指向其他网页的所有链接）。（我在此拉取请求 #17 中添加）
现在，它需要对重新结构化文本中的特定 lint 检查和其他标准进行更多检查。这可以通过 restructuredtext-lint 来实现，但需要更多研究，并将作为我的 GSoD 项目的一部分来完成。
[ 3. 添加“使用入门”部分 ]
本部分将作为新手的起点，其中汇集了最基本、最重要的文档，可帮助您开始使用 Aboutcode 项目。
每个 Aboutcode 项目都会包含此部分，包括 Scancode-Toolkit、Scancode-Workbench、Deltacode 等。
[ 4. 根据 4 种文档功能进行重构 ]
现有文档未明确按照 4 种文档功能（教程、方法、参考和说明）进行构建。我建议相应地进行结构化，根据需要添加更多信息/说明/指针。这适用于所有 AboutCode 项目及其文档。以下是我提议且希望在这个项目中进行的两个 Scancode-Toolkit 文档结构调整的两个示例。我们将在本文档的其余部分进行类似的更改。
[ 5. 重构开发页面 (Scancode-Toolkit) ]
可以添加有关代码/API 的更多信息，使其更便于开发者使用。
可以包含指向 [ 2. 讨论了上面的“代码扫描”部分。此链接将对扫描如何运作的说明与用于执行扫描的代码相关联。
就像这些文件夹包含扫码器工具包的不同部分一样，您可以结合有关扫码器工作原理的讨论，通过 API 详细了解各个文件夹的用途。
- [ cluecode : plugins for scanning licenses, copyrights, urls, emails ]
- [ commoncode : helper classes and functions]
- [ extractcode ：提取不同的归档格式 ]
- [ formattedcode : output formatting for different output file formats ]
- [ licensedcode : licence detection code ]
- [ packagedcode : parsing various package formats ]
- [ plugincode : classes for the plugins architecture ]
- [ summarycode : summarizes scan on detected licenses ]
- [ textcode : handles text parsing ]
- [ typecode : 处理文件类型决定 ]
- [ scancode : CLI and API to scancode, the core part ]
本子部分将在相应的子部分中包含有关 scancode-toolkit 的这些部分的详细信息/API。
开发指南将位于其他网页或其他包含更小子部分的部分中。
[ 6. 重构常见问题解答页面 (Scancode-Toolkit) ]
目前，常见问题解答页面上有些问题可以更好地解答，并且应分别以“如何”文档、教程和参考文档的形式进行编写。
- ScanCode 如何运作？
[ 2. 代码扫描的讨论]，并将在一个完全独立的部分中进行更详细的介绍。
- 如何为增强型检测添加新的许可规则？
我们之前在“改进现有操作方法”中讨论过此问题，相关文档将移至该部分。
- 如何添加新的许可检测规则？
您可以另行制作另一个“操作方法”帖子，并做进一步说明。
- 如何开始开发？
我们已经提供了单独的开发页面，其中包含的信息与此页面有很大重叠。我们在前面已经讨论了开发页面的调整。
- 新发行的作品剪辑步骤
可以换成单独的“如何剪辑新版本”的视频。
- 查找更多常见问题解答，这些问题旨在解答与项目相关的常规问题，不属于“如何”/“教程”类别。
如未另行说明，那么本页面中的内容已根据知识共享署名 4.0 许可获得了许可。有关详情，请参阅 Google 开发者网站政策。Java 是 Oracle 和/或其关联公司的注册商标。
最后更新时间 (UTC)：2025-07-25。
[null,null,["最后更新时间 (UTC)：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."]]
