本頁面包含 Google 技術文件季度接受的技術寫作專案詳細資料。
專案摘要
- 開放原始碼組織：
- AboutCode
- 技術撰稿人：
- ayansinha
- 專案名稱：
- 參考 scancode-toolkit 中的指令列選項，並重新整理 aboutcode.readthedocs.io 的 AboutCode 說明文件結構
- 專案長度：
- 標準長度 (3 個月)
Project description
[ 1. Scancode-Toolkit 指令列選項 ]
Scancode-Toolkit 提供多項指令列選項，可自訂掃描方式、輸出格式，以及其他選項，例如掃描後外掛程式。這些選項目前沒有適當的說明文件，且只能透過「--help」或「-h」標記使用。本專案旨在製作完整的說明文件，說明以下內容：
[ 1. 可透過指令列提供的所有選項 ]
- 目標：透過指令列列出所有可能的選項。
- 基本總覽：首先，我們將討論預設的掃描選項，並提供輸出結果範例。簡短圖表/說明，說明如何執行掃描作業。
以下的預設行為可做為其他選項如何變更掃描作業和輸出內容的參考。
我們將詳細討論這些內容，並在後續章節中提供以下資訊。
[ 2. 啟動版本結構 ]
- 目標：啟動版本管理系統，妥善維護跨版本選項/API 和說明文件的變更。
- 問題：目前 Wiki 和 ReadTheDocs 頁面中的說明文件適用於舊版，需要進行重大重組。
- 基本簡介： 在這個版本中，已更新/可更新的掃描碼工具包部分如下：
- 指令列選項
- API
- 說明文件 (尚未啟動) 在版本和版本中，指令列選項和 API 已變更，說明文件也必須遵循相關規定，否則將造成使用者混淆。指令列公用程式 [ --help ] 已針對選項的任何變更進行更新，可用於複製說明文件中的版本管理。
[ 3. 這些選項在不同情況下的使用方式 ]
- 目標：本節將提供基本摘要，說明如何在不同情況下使用 Scancode-Toolkit 的掃描結果，以及提供這類功能的 Scancode-Toolkit 選項。
- 基本總覽：本節提供各種用途情境範例，以及這些情境的建議選項。
- 注意：必須取得導師的重要協助，才能提供 Scancode-Toolkit 各種用途的參考資料和指標。
[ 4. 這些選項會在掃描和輸出作業中變更什麼 ]
- 目標：本節將提供基本摘要，說明如何在不同情況下使用 scancode-toolkit 的掃描結果，以及提供這類功能的 Aboutcode 工具。
- 基本總覽：這些選項會變更掃描的執行方式。在前導章節中，我們會說明基本預設情況 [1. 透過命令列提供的所有選項]，本節將比較所有選項對這個預設情境帶來的變化。
[ 5. 輸出格式和範例 ]
- 目標：本節將提供基本摘要，說明如何在不同情況下使用 scancode-toolkit 的掃描結果，以及提供這類功能的 Aboutcode 工具。
- 基本簡介：Scancode-Tool 有標記，可指定要產生掃描結果的不同輸出格式。這些是 -
這個部分 - 並詳細說明
- 提供輸出格式的範例
- 提供與輸出格式和用途相對應的其他連結
- 掃描結果儲存在輸出檔案的方式。這也與「如何產生這些不同格式」相關，這部分會在 [2. 討論程式碼掃描 ] 的討論。
[ 6. 商用掃描代碼輸出格式 ]
- 目標：說明 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. 討論程式碼掃描 ] 的討論，獨立部分包含更多詳細資訊。
- 如何新增加強型偵測功能適用的新授權規則？ 這個問題在「改善現有操作說明」一文中已討論過，相關說明文件會移至該處。
- 如何新增授權偵測規則？這可以單獨做為另一篇「操作說明」文章，並進一步詳述。
- 如何開始開發？我們已經有一個獨立的開發頁面，而且兩者資訊重疊的程度相當高。我們在前文中討論過開發頁面的重構作業。
- 剪輯新版本的步驟。這可以轉換為單獨的「如何剪輯新版本」。
- 查看更多常見問題，這些問題會回答專案的一般問題，且不屬於「操作說明」/「教學課程」類別。