本頁詳細說明 Google 文件季度接受的一項技術撰寫專案詳細資料。
專案摘要
- 開放原始碼組織：
- AboutCode
- 技術撰稿人：
- 愛南海
- 專案名稱：
- 掃描程式碼工具包中的指令列選項參考資料，並重新整理 AboutCode 說明文件的結構，網址為 aboutcode.readthedocs.io
- 專案長度：
- 標準長度 (3 個月)
Project description
[ 1. Scancode-Toolkit 命令行選項 ]
Scancode-Toolkit 提供一系列的命令列選項，可以自訂掃描執行方式、輸出格式以及掃描後外掛程式等數個其他選項。這些選項目前未提供用於說明這些選項的適當說明文件，只能透過「--help」或「-h」標記存取。本專案旨在製作完整說明文件，說明：
[ 1. 所有選項 可透過指令列取得 ]
- 目標：透過指令列列出所有可用選項的完整清單。
- 基本總覽：首先，我們會討論預設的掃描選項，並提供輸出範例。描述掃描方式的簡短圖形/說明。
此後，這個預設行為可當做其他選項變更掃描和輸出內容的參考。
我們會詳細討論上述內容，並會在後續章節中說明下列資訊。
[ 2. 啟動版本設定結構 ]
- 目標：啟動版本管理系統，以妥善維護跨版本選項/API 和說明文件的變更。
- 問題：維基和 ReadTheDoc 網頁介紹較舊版本，且需要大幅調整程式碼結構。
- 基本總覽： Scancode-kit 中已更新/能在版本中更新的部分
- 指令列選項
- API
- 說明文件 (即將啟動) 各版本和版本的指令列選項和 API 已變更，且說明文件也必須遵循，否則可能會造成使用者嚴重混淆。由於指令列公用程式 [ --help ] 已完成更新選項的變更項目，因此可用於複製說明文件中的版本管理。
[ 3. 這些選項在不同情況下的使用方式 ]
- 目標：本節提供掃描程式碼工具包掃描結果的基本摘要，說明掃描程式碼工具包的掃描結果在不同原因的運用方式，以及提供這類功能的 Scancode-Toolkit 選項。
- 基本總覽：本節提供不同的用途示例，以及這些情境適用的建議選項。
- 注意：在這部分需要導師的協助，才能輸入有關 Scancode-Toolkit 各種用途的輸入內容和指示。
[ 4. 這兩個選項在掃描和輸出中的變化 ]
- 目標：本節提供掃描程式碼工具包掃描結果的基本摘要，說明掃描程式碼工具包的掃描結果在不同原因中的用途，以及提供這類功能的「Aboutcode」工具。
- 基本總覽：選項會變更掃描作業的行為。 下方為基本的預設案例說明 [ 1. 指令列 ] 和這個預設情境提供的所有選項都會比較。
[ 5. 輸出格式及其範例 ]
- 目標：本節提供掃描程式碼工具包掃描結果的基本摘要，說明掃描程式碼工具包的掃描結果在不同原因中的用途，以及提供這類功能的「Aboutcode」工具。
- 基本總覽：Scancode-Tool 含有指定不同輸出格式的掃描結果。這些是 -
這部分將 - 並詳細說明輸出格式
- 針對輸出格式提供範例
- 提供與輸出格式相對應的連結
- 掃描結果在輸出檔案中的儲存方式。此連結也會說明這些不同格式的產生方式 (詳情請參閱 [ 2. 含程式碼掃描的討論 ].
[ 6. 商業用途掃描碼輸出格式 ]
- 目標：說明掃描碼輸出格式的商業用途 在 GSoD 的提案清單中，掃描程式碼輸出格式是做為參考想法的參考。本節實作的方式相同。
- 注意：在這部分需要導師的協助，才能輸入 Scancode-Toolkit 各種業務用途的輸入內容和指示。
[ 7. 其他 AboutCode 專案如何使用這些輸出內容進行更多分析 ]
- 目標：本節提供掃描程式碼工具包掃描結果的基本摘要，說明掃描程式碼工具包的掃描結果在不同原因中的用途，以及提供這類功能的「Aboutcode」工具。
- 基本總覽：
- Scancode-Workbench 此部分說明如何透過電腦版應用程式以視覺化方式呈現結果，並提供指向 Scancode-workbench 說明文件的指標，以便獲得更多資訊。必要時，將會新增必要文件至 Scancode-workbench。
- Deltacode 掃描碼如何由 Deltacode 取得，以確定兩個程式碼集之間的檔案層級差異。
[ 2. 重新整理 AboutCode 說明文件的結構 ]
此部分包含關於「關於」說明文件的一些變更
[ 1. 版本管理系統 ]
在 [ 1. Scancode-Toolkit 命令行選項 -> 2. 啟動版本管理結構] 說明指令列選項的版本管理問題。說明文件的其他部分也包含相同內容，包含版本專屬指令/資訊，以免造成混淆。
[ 2. 訂定說明文件標準和測試 ]
說明文件已有測試 spinx-build (建構所有頁面並檢查所有 Sphinx 語法錯誤) 和透過 Travis-CI 進行持續整合檢查的連結檢查 (檢查說明文件中連往其他網頁的所有連結)。(我在這份提取要求 #17 中新增的項目) 現在，還需要針對重新結構化文字和其他標準，針對特定程式碼檢查進行更多檢查。在此情況下，使用 restructuredtext-lint 即可實現這一點，但還需要進行更多研究，並將做為 GSoD 專案的一部分。
[ 3. 新增「開始使用」部分 ]
其中將為新手入門說明，包含最基本和重要文件的合輯，協助您快速上手。 每個 Aboutcode 專案都會有這個部分，包括 Scancode-Toolkit、Scancode-Workbench 和 Deltacode 等。
[ 4. 根據 4 Document 函式進行重組 ]
現有的說明文件並未在 4 個文件函式中明確建立結構：教學課程、操作說明、參考資料與說明。我建議根據這些目標架構，視情況加入更多資訊/說明/指標。此保留適用於所有 AboutCode 專案及其說明文件。以下是 Scancode-Toolkit 文件重組的兩個範例，接下來就是這項專案。其餘說明文件也會進行類似的變更。
[ 5. 重新建構開發頁面 (Scancode-Toolkit) ]
您可以新增程式碼/API 的詳細資訊，讓開發人員更容易理解。也可以使用 [ 2. 上述「程式碼掃描」部分的討論。此連結會說明掃描功能如何與用來執行掃描的代碼。 就像這些資料夾包含 Scancode-kit 的不同部分，我們可以運用 API 以及掃描碼運作方式的討論，詳細描述這些資料夾的使用方法。
- [ cluecode : 用來掃描授權、版權、網址、電子郵件的外掛程式 ]
- [commoncode : helper class 和 function]
- [ 擷取程式碼： 擷取不同的封存格式 ]
- [格式化程式碼：不同輸出檔案格式的輸出格式 ]
- [授權代碼：授權偵測代碼 ]
- [ packagedcode ：剖析各種套件格式 ]
- [ plugincode : 外掛程式架構的類別 ]
- [摘要程式碼：針對偵測到的授權提供掃描摘要 ]
- [ 文字碼 ：處理文字剖析 ]
- [ typecode ：處理檔案類型的決定 ]
- [ 掃描碼：CLI 和 API 可掃描程式碼，核心部分 ]
這個子區段會在子章節中，針對掃描程式碼工具包的這些部分提供詳細資訊/API。 「開發指南」會放在其他網頁，或有其他區段的子區段內。
[ 6. 重新建構常見問題網頁 (Scancode-Toolkit) ]
目前的「常見問題」網頁含有其他有助於解決的問題，因此應分別建立獨立的「操作說明」、「教學課程」和「參考文件」。
- ScanCode 如何運作？ 這個問題已在 [ 2. 討論程式碼掃描 ] 亦獨立部分提供更多詳細資料。
- 如何新增強化偵測的授權規則？我們先前已在「改善現有教學示範」中討論過這個問題，因此說明文件將會移至該處。
- 如何新增授權偵測規則？ 您可以把這些內容另外寫在另一篇「教學指南」貼文中，再詳細說明。
- 如何開始開發？既然已經有獨立的開發頁面，而且資訊上有許多重疊之處。重新建構開發頁面的結構已在前文討論。
- 剪下新版本的步驟 這可以轉換成獨立的「如何剪輯新版本」。
- 尋找更多常見問題解答，找出與專案相關的一般問題，而非屬於「操作說明/教學」類別。