本页详细介绍了 Google 文档季收录的技术文案项目。
项目摘要
- 开源组织：
- AboutCode
- 技术文档工程师：
- 阿雅辛哈
- 项目名称：
- 在 aboutcode.readthedocs.io 上添加了 scancode-toolkit 命令行选项参考文档，并重组了 AboutCode 文档的结构
- 项目时长：
- 标准时长（3 个月）
Project description
[ 1. Scancode-Toolkit 命令行选项 ]
Scancode-Toolkit 提供了一系列命令行选项，可用于自定义扫描方式、输出格式以及扫描后插件等其他选项。目前，这些选项还没有适当的文档来说明，只能通过“--help”或“-h”标志使用。此项目旨在制作完整的文档，说明以下内容：
[ 1. 通过命令行提供的所有选项 ]
- 目标：通过命令行列出所有可能的选项。
- 基本概览：首先，我们将介绍默认扫描选项，并附上输出示例。关于如何执行扫描的简短图形/说明。
以下部分将以此默认行为为参考，介绍其他选项如何更改扫描和输出。
我们将详细讨论这些内容，并包含以下信息，如以下部分所述。
[ 2. 启动版本控制结构 ]
- 目标：启动版本控制系统，以妥善维护跨版本选项/API 和文档更改。
- 问题：目前，维基中的文档和 ReadTheDocs 页面适用于旧版本，需要进行重大重构。
- 基本概览：扫码工具包在该版本中更新/可更新的部分如下：
- 命令行选项
- 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 如何获取扫码结果，以确定两个代码库之间的文件级差异。
[ 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. 代码扫描的讨论]，并将在一个完全独立的部分中进行更详细的介绍。
- 如何为增强型检测添加新的许可规则？ 我们之前在“改进现有操作方法”中讨论过此问题，相关文档将移至该部分。
- 如何添加新的许可检测规则？ 您可以另行制作另一个“操作方法”帖子，并做进一步说明。
- 如何开始开发？ 我们已经提供了单独的开发页面，其中包含的信息与此页面有很大重叠。我们在前面已经讨论了开发页面的调整。
- 新发行的作品剪辑步骤 可以换成单独的“如何剪辑新版本”的视频。
- 查找更多常见问题解答，这些问题旨在解答与项目相关的常规问题，不属于“如何”/“教程”类别。