雲端原生運算基金會 (CNCF) 專案

本頁將詳細說明 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 參考資料的翻譯版本。