本頁將詳細說明 Google Season of Docs 接受的技術文件寫作專案。
專案摘要
- 開放原始碼組織：
- 雲端原生運算基金會 (CNCF)
- 技術撰稿人：
- feloy
- 專案名稱：
- 更新 Kubernetes 網站提供 API 參照的方式
- 專案長度：
- 標準長度 (3 個月)
Project description
目前，Kubernetes API 參考資料是大型 HTML 文件，是由 script 從 Swagger 規格產生，並在 網站存放區外部代管，然後加入這個網站存放區。
另一方面，Kubernetes 說明文件網站是使用 Hugo 建構，並使用 Docsy Hugo 主題，從網站存放區中以 Markdown 格式編寫的說明文件中建構。
這項專案的目標是將產生的 Kubernetes API 參照項目整合至建構說明文件網站的程序。
具體來說，我們會聚焦於 swaggerui 簡短程式碼，也就是 Docsy Hugo 主題和特定工具提供的 swagger-ui 包裝函式，可在 Kubernetes 說明文件的流程中插入 API 規格的部分內容。
由於 swagger-ui 只能輸出 swagger 檔案中描述的完整規格，而無法輸出部分規格 (請參閱 8)，因此您需要使用特定工具。Kubernetes API 太大，無法只顯示其中一部分(輸出內容範例)。我們將考慮兩種方法：
第一個方法是建立多個 Swagger 檔案，每個 Kubernetes API 群組 (core/v1、apps/v1、...) 皆來自 (10) 提供的來源，再將這些檔案做為 Swaggerui 排序代碼，輸入 Kubernetes 說明文件網站的特定位置。
第二種方法是建立工具，以 (11) 所述方式取得 Kubernetes API 的完整 swagger 檔案，並針對特定端點或有限數量的端點輸出新的 swagger 檔案，以及相關聯的資源和定義，然後在 Kubernetes 說明文件網站的特定位置使用這些 swagger 檔案做為 swaggerui 短代碼的輸入內容。
由於規格來源 (10 和 11) 位於說明文件來源以外的其他存放區，我們需要找到方法，能在說明文件存放區進行變更時自動更新。
Kubernetes 說明文件提供多種語言版本，我們會特別留意發布 Kubernetes API 參考資料的翻譯版本。