本页包含已获 Google 文档季 计划接受的技术写作项目的详细信息。
项目摘要
- 开源组织：
- AboutCode
- 技术文档工程师：
- ayansinha
- 项目名称：
- scancode-toolkit 中的命令行选项参考文档，并重新整理了 aboutcode.readthedocs.io 上 AboutCode 文档的结构
- 项目时长：
- 标准时长（3 个月）
Project description
[ 1. Scancode-Toolkit 命令行选项 ]
Scancode-Toolkit 提供了许多命令行选项，可用于自定义扫描的执行方式、输出格式以及扫描后插件等其他选项。这些选项目前没有适当的文档来解释它们，只能通过“--help”或“-h”标志来使用。此项目旨在提供完整的文档，说明：
[ 1. 通过命令行提供的所有选项 ]
- 目标：通过命令行列出所有可能的选项。
- 基本概览：首先，我们将讨论默认扫描选项，并提供输出示例。有关如何执行扫描的简短图示/说明。
此后，此默认行为将作为参考，用于了解其他选项如何更改扫描和输出。
这些内容将在后续部分中详细讨论，并将包含以下信息。
[ 2. 启动版本控制结构 ]
- 目标：启动版本控制系统，以妥善维护跨版本选项/API 和文档更改。
- 问题：目前，维基和 ReadTheDocs 页面中的文档适用于旧版本，需要进行重大重组。
- 基本概览：scancode-toolkit 中已更新/可在版本中更新的部分包括
- 命令行选项
- API
- 文档（待启动） 命令行选项和 API 会在不同版本和发布版本中发生变化，文档也必须随之更新，否则会给用户带来极大的困惑。命令行实用程序 [ --help ] 已经针对选项中的任何更改进行了更新，可用于复制文档中的版本控制。
[ 3. 如何在不同情况下使用这些选项 ]
- 目标：本部分将简要总结如何将 Scancode-Toolkit 的扫描结果用于不同用途，以及提供此类功能的 Scancode-Toolkit 选项。
- 基本概览：此部分提供了不同的使用情形示例，以及在这些情形下建议使用的选项。
- 注意：在提供有关 Scancode-Toolkit 的各种应用场景的输入和指针方面，本部分需要导师的大力帮助。
[ 4. 这些选项会如何改变扫描和输出 ]
- 目标：本部分将简要总结如何在不同情况下使用 scancode-toolkit 的扫描结果，以及提供此类功能的 Aboutcode 工具。
- 基本概览：这些选项会更改扫描的执行方式。 在前面的部分 [ 1. 所有可通过命令行获得的选项，以及本部分将比较所有选项对此默认方案带来的变化。
[ 5. 输出格式及其示例 ]
- 目标：本部分将简要总结如何在不同情况下使用 scancode-toolkit 的扫描结果，以及提供此类功能的 Aboutcode 工具。
- 基本概览：Scancode-Tool 具有一些标志，用于指定生成扫描结果的不同输出格式。这些是 -
这部分将 - 详细说明输出格式
- 提供有关输出格式的示例
- 提供与输出格式及其用途相对应的其他链接
- 扫描结果在输出文件中的存储方式。 这还链接到“这些不同格式是如何生成的”，这将在 [ 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. 设置文档标准和测试 ]
该文档已通过 Travis-CI 进行持续集成，并针对 spinx-build（构建所有页面并检查整个文档中的 Sphinx 语法错误）和链接检查（检查文档中指向其他网页的所有链接）进行了测试。（由我在此 pull 请求 #17 中添加）现在，它需要对 reStructuredText 和其他标准中的特定 linting 进行更多检查。这可以通过 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 结合有关 scancode 工作方式的讨论来详细说明。
- [ cluecode : plugins for scanning licenses, copyrights, urls, emails ]
- [ commoncode : helper classes and functions]
- [ extractcode：提取不同的归档格式 ]
- [ formattedcode : 不同输出文件格式的输出格式 ]
- [ licensedcode : 许可检测代码 ]
- [ packagedcode：解析各种软件包格式 ]
- [ plugincode：插件架构的类 ]
- [ summarycode : summarizes scan on detected licenses ]
- [ textcode : 处理文本解析 ]
- [ typecode：处理文件类型确定 ]
- [ scancode : CLI 和 API 到扫描码，核心部分 ]
此子部分将相应地在子子部分中包含有关扫描代码工具包的这些部分的详细信息/API。 开发指南将位于另一个页面或另一个包含较小子部分的版块中。
[ 6. 重构常见问题解答页面 (Scancode-Toolkit) ]
目前，常见问题解答页面中的问题可以更好地解答，并且应分别以单独的操作指南、教程和参考文档的形式呈现。
- ScanCode 的工作原理是什么？ 此问题在 [ 2. 讨论解释代码扫描 ]，并将成为一个完全独立的章节，其中包含更多详细信息。
- 如何添加新的许可规则以增强检测功能？ 我们之前已在“改进现有操作指南”中讨论过此问题，相关文档将移至该部分。
- 如何添加新的许可检测规则？ 这可以单独写成另一篇“操作指南”博文，并进行详细说明。
- 如何开始进行开发？ 我们已经有一个单独的开发页面，并且信息重叠程度很高。上文已讨论过开发页面的重组。
- 发布新版本的步骤 这可以转换为单独的“如何发布新版本”。
- 查找更多常见问题解答，其中包含有关项目的常规问题，但不属于“操作方法”/“教程”类别。