本頁面包含 Google Season of Docs 接受的技術寫作專案詳細資料。
專案摘要
- 開放原始碼機構：
- AboutCode
- 技術撰稿人：
- ayansinha
- 專案名稱：
- scancode-toolkit 指令列選項的參考資料，並在 aboutcode.readthedocs.io 重新整理 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 工具設有旗標，可指定產生掃描結果時使用的輸出格式。這些是 -
這部分會 - 詳細說明輸出格式
- 舉例說明輸出格式
- 提供與輸出格式及其用途相應的其他連結
- 掃描結果在輸出檔案中的儲存方式。 這也連結至「如何產生這些不同格式」，將在 [ 2. 討論，說明程式碼掃描功能]。
[ 6. 商業用途的掃描碼輸出格式 ]
- 目標：說明掃描碼輸出格式的業務用途。在 GSoD 構想清單中，掃描碼輸出格式是參考構想。這個部分會實作相同功能。
- 注意：這部分需要導師提供大量協助，包括有關 Scancode-Toolkit 各種業務用途的輸入內容和指標。
[ 7. 其他 AboutCode 專案如何使用這些輸出內容進行更多分析 ]
- 目標：本節將簡要說明如何將 scancode-toolkit 的掃描結果用於不同用途，以及提供這類功能的 Aboutcode 工具。
- 基本總覽：
- Scancode-Workbench 本節說明如何使用電腦版應用程式將結果視覺化，並提供 scancode-workbench 文件指標，以便取得更多相關支援。如有必要，會將必要文件新增至 scancode-workbench。
- Deltacode Deltacode 如何採用掃描碼結果，判斷兩個程式碼集之間的檔案層級差異。
[ 2. 重新整理 AboutCode 說明文件的結構
這部分包含對 Aboutcode 說明文件的一連串變更，
[ 1. 版本管理系統 ]
在 [ 1. Scancode-Toolkit 指令列選項 -> 2. 啟動版本控管結構] 中提及指令列選項的版本控管問題。文件其他部分也需要這麼做，因為這些部分包含特定版本的指令/資訊，否則會造成混淆。
[ 2. 設定文件標準和測試 ]
說明文件已透過 Travis-CI 進行持續整合，並對 spinx-build (建構所有頁面並檢查整個 Sphinx 語法錯誤) 和連結檢查 (檢查說明文件中所有其他網頁的連結) 進行測試。(我在這個 Pull Request #17 中新增) 現在需要針對 reStructured Text 和其他標準中的特定 Linting 進行更多檢查。這項功能可透過 restructuredtext-lint 達成，但需要更多研究，並將做為 GSoD 專案的一部分。
[ 3. 新增「開始使用」專區 ]
這將做為新手的入門專區，彙整最基本且重要的文件，協助他們開始使用 Aboutcode 專案。 每個 Aboutcode 專案都會有這個部分，包括 Scancode-Toolkit、Scancode-Workbench、Deltacode 等。
[ 4. 根據 4 個文件功能重新建構
現有說明文件並未明確劃分為 4 個文件功能：教學課程、操作說明、參考資料和說明。我建議據此調整結構，並視需要加入更多資訊/說明/指標。這適用於所有 AboutCode 專案及其說明文件。以下是兩個 Scancode-Toolkit 文件重組的範例，我建議並希望在本專案中繼續進行。其餘說明文件也會進行類似變更。
[ 5. Restructuring the Development Page (Scancode-Toolkit) ]
可以加入更多程式碼/API 相關資訊，讓開發人員更容易使用。 可以有連結至 [ 2. 請參閱上方的「程式碼掃描」] 部分的討論內容。這會將掃描運作方式的說明，連結至執行掃描時使用的程式碼。這些資料夾包含 scancode-toolkit 的不同部分，因此可搭配 API 詳述個別用途，並討論 scancode 的運作方式。
- [ cluecode : plugins for scanning licenses, copyrights, urls, emails ]
- [ commoncode : helper classes and functions]
- [ extractcode : extracts different archive formats ]
- [ 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 : handles file type determinations ]
- [ scancode : CLI and API to scancode, the core part ]
這個小節會相應地在子小節中，詳細說明 scancode-toolkit 的這些部分/API。「開發指南」會顯示在另一個頁面或另一個區段，並包含較小的子區段。
[ 6. 重新架構常見問題頁面 (Scancode-Toolkit) ]
目前常見問題頁面上的問題可以有更好的解答，且應分別以「操作說明」、「教學課程」和「參考文件」的形式呈現。
- ScanCode 的運作方式為何？ 這個問題參照了 [ 2. 討論內容會說明程式碼掃描，並在完全獨立的章節中提供更多詳細資訊。
- 如何新增授權規則，提升偵測準確度？我們已在「改善現有操作說明」中討論過這個問題，相關文件將移至該處。
- 如何新增授權偵測規則？這可以另外製作成「操作說明」文章，並詳細說明。
- 如何開始開發？ 因為我們已有獨立的開發頁面，且資訊有許多重疊之處。如上所述，開發人員頁面已完成重組。
- 發布新版本的步驟 這可以轉換成獨立的「如何發布新版本」。
- 如需更多常見問題，請參閱「如何」/「教學課程」類別以外的專案一般問題解答。