AboutCode 專案
透過集合功能整理內容
你可以依據偏好儲存及分類內容。
本頁面包含 Google 技術文件季度接受的技術寫作專案詳細資料。
專案摘要
- 開放原始碼組織：
- AboutCode
- 技術撰稿人：
- ayansinha
- 專案名稱：
- 參考 scancode-toolkit 中的指令列選項，並重新整理 aboutcode.readthedocs.io 的 AboutCode 說明文件結構
- 專案長度：
- 標準長度 (3 個月)
Project description
Scancode-Toolkit 提供多項指令列選項，可自訂掃描方式、輸出格式，以及其他選項，例如掃描後外掛程式。這些選項目前沒有適當的說明文件，且只能透過「--help」或「-h」標記使用。本專案旨在製作完整的說明文件，說明以下內容：
[ 1. 可透過指令列提供的所有選項 ]
- 目標：透過指令列列出所有可能的選項。
- 基本總覽：首先，我們將討論預設的掃描選項，並提供輸出結果範例。簡短圖表/說明，說明如何執行掃描作業。
以下的預設行為可做為其他選項如何變更掃描作業和輸出內容的參考。
我們將詳細討論這些內容，並在後續章節中提供以下資訊。
[ 2. 啟動版本結構 ]
- 目標：啟動版本管理系統，妥善維護跨版本選項/API 和說明文件的變更。
- 問題：目前 Wiki 和 ReadTheDocs 頁面中的說明文件適用於舊版，需要進行重大重組。
- 基本簡介：
在這個版本中，已更新/可更新的掃描碼工具包部分如下：
- 指令列選項
- 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 指令列選項 -> 2. 啟動版本結構] 提到了指令列選項的版本問題。說明文件的其他部分也必須遵循相同的做法，因為這些部分可能包含會造成混淆的版本專屬指令/資訊。
[ 2. 設定文件標準和測試 ]
說明文件已透過 Travis-CI 的持續整合功能，針對 spinx-build (建構所有網頁並檢查 Sphinx 語法錯誤) 和連結檢查 (檢查說明文件中所有連往其他網頁的連結) 進行測試。(我已在這個提取要求 #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 和討論區瞭解如何使用這些資料夾。
- [ cluecode : plugins for scanning licenses, copyrights, urls, emails ]
- [commoncode：輔助類別和函式]
- [extractcode：擷取不同封存檔格式 ]
- [ formattedcode : output formatting for different output file formats ]
- [ licensedcode : licence detection code ]
- [ packagedcode : parsing various package formats ]
- [plugincode : 外掛程式架構的類別 ]
- [summarycode : 摘要代碼：摘要掃描偵測到的執照 ]
- [ textcode : 處理文字剖析 ]
- [ typecode : 處理檔案類型決定 ]
- [ scancode : CLI and API to scancode, the core part ]
這個子區段將根據子節段，提供掃描程式碼工具包的這些部分的詳細資訊/API。但是開發指南會顯示在其他頁面或包含較小的子區段。
[ 6. 重新建構常見問題頁面 (Scancode-Toolkit) ]
目前的常見問題頁面含有較實用的解答，建議分別採用不同的說明、教學課程和參考文件。
- ScanCode 的運作方式為何？
這個問題在 [ 2. 討論程式碼掃描 ] 的討論，獨立部分包含更多詳細資訊。
- 如何新增加強型偵測功能適用的新授權規則？
這個問題在「改善現有操作說明」一文中已討論過，相關說明文件會移至該處。
- 如何新增授權偵測規則？這可以單獨做為另一篇「操作說明」文章，並進一步詳述。
- 如何開始開發？我們已經有一個獨立的開發頁面，而且兩者資訊重疊的程度相當高。我們在前文中討論過開發頁面的重構作業。
- 剪輯新版本的步驟。這可以轉換為單獨的「如何剪輯新版本」。
- 查看更多常見問題，這些問題會回答專案的一般問題，且不屬於「操作說明」/「教學課程」類別。
除非另有註明，否則本頁面中的內容是採用創用 CC 姓名標示 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."]]
