生成 Kubernetes API 的參考文件
本頁面顯示瞭如何更新 Kubernetes API 參考文件。
Kubernetes API 參考文件是使用 kubernetes-sigs/reference-docs 程式碼生成工具，從 Kubernetes OpenAPI 規範 構建的。
如果您發現生成的文件中存在錯誤，您需要 在 upstream 進行修復。
如果您只需要從 OpenAPI 規範重新生成參考文件，請繼續閱讀本頁。
準備工作
要求
您需要一臺執行 Linux 或 macOS 的機器。
您需要安裝以下工具
您的
PATH環境變數必須包含必需的構建工具，例如Go二進位制檔案和python。您需要了解如何向 GitHub 儲存庫建立拉取請求。這包括建立儲存庫的個人分支。有關更多資訊，請參閱 從本地克隆進行工作。
設定本地倉庫
建立本地工作區並設定您的 GOPATH
mkdir -p $HOME/<workspace>
export GOPATH=$HOME/<workspace>
克隆以下倉庫的本地副本
go get -u github.com/kubernetes-sigs/reference-docs
go get -u github.com/go-openapi/loads
go get -u github.com/go-openapi/spec
如果您還沒有 kubernetes/website 倉庫，請立即獲取
git clone https://github.com/<your-username>/website $GOPATH/src/github.com/<your-username>/website
克隆 kubernetes/kubernetes 倉庫，並將其命名為 k8s.io/kubernetes
git clone https://github.com/kubernetes/kubernetes $GOPATH/src/k8s.io/kubernetes
您克隆的 kubernetes/kubernetes 倉庫的基準目錄是
$GOPATH/src/k8s.io/kubernetes。其餘步驟將您的基準目錄稱為<k8s-base>。您克隆的 kubernetes/website 倉庫的基準目錄是
$GOPATH/src/github.com/<your username>/website。其餘步驟將您的基準目錄稱為<web-base>。您克隆的 kubernetes-sigs/reference-docs 倉庫的基準目錄是
$GOPATH/src/github.com/kubernetes-sigs/reference-docs。其餘步驟將您的基準目錄稱為<rdocs-base>。
生成 API 參考文件
本節介紹如何生成 已釋出的 Kubernetes API 參考文件。
設定構建變數
- 將
K8S_ROOT設定為<k8s-base>。 - 將
K8S_WEBROOT設定為<web-base>。 - 將
K8S_RELEASE設定為您要構建的文件的版本。例如，如果您想構建 Kubernetes 1.17.0 的文件，請將K8S_RELEASE設定為 1.17.0。
例如
export K8S_WEBROOT=${GOPATH}/src/github.com/<your-username>/website
export K8S_ROOT=${GOPATH}/src/k8s.io/kubernetes
export K8S_RELEASE=1.17.0
建立版本化目錄並獲取 Open API 規範
updateapispec 構建目標會建立版本化的構建目錄。目錄建立後，Open API 規範將從 <k8s-base> 倉庫獲取。這些步驟可確保配置檔案和 Kubernetes Open API 規範的版本與釋出版本匹配。版本化目錄的名稱遵循 v<major>_<minor> 的模式。
在 <rdocs-base> 目錄中，執行以下構建目標
cd <rdocs-base>
make updateapispec
構建 API 參考文件
copyapi 目標會構建 API 參考文件，並將生成的資料夾複製到 <web-base> 中的目錄。在 <rdocs-base> 中執行以下命令
cd <rdocs-base>
make copyapi
驗證這兩個檔案是否已生成
[ -e "<rdocs-base>/gen-apidocs/build/index.html" ] && echo "index.html built" || echo "no index.html"
[ -e "<rdocs-base>/gen-apidocs/build/navData.js" ] && echo "navData.js built" || echo "no navData.js"
轉到本地 <web-base> 的根目錄，檢視哪些檔案已修改
cd <web-base>
git status
輸出類似於：
static/docs/reference/generated/kubernetes-api/v1.34/css/bootstrap.min.css
static/docs/reference/generated/kubernetes-api/v1.34/css/font-awesome.min.css
static/docs/reference/generated/kubernetes-api/v1.34/css/stylesheet.css
static/docs/reference/generated/kubernetes-api/v1.34/fonts/FontAwesome.otf
static/docs/reference/generated/kubernetes-api/v1.34/fonts/fontawesome-webfont.eot
static/docs/reference/generated/kubernetes-api/v1.34/fonts/fontawesome-webfont.svg
static/docs/reference/generated/kubernetes-api/v1.34/fonts/fontawesome-webfont.ttf
static/docs/reference/generated/kubernetes-api/v1.34/fonts/fontawesome-webfont.woff
static/docs/reference/generated/kubernetes-api/v1.34/fonts/fontawesome-webfont.woff2
static/docs/reference/generated/kubernetes-api/v1.34/index.html
static/docs/reference/generated/kubernetes-api/v1.34/js/jquery.scrollTo.min.js
static/docs/reference/generated/kubernetes-api/v1.34/js/navData.js
static/docs/reference/generated/kubernetes-api/v1.34/js/scroll.js
更新 API 參考索引頁
在為新版本生成參考文件時，請更新檔案 <web-base>/content/en/docs/reference/kubernetes-api/api-index.md 中的新版本號。
開啟
<web-base>/content/en/docs/reference/kubernetes-api/api-index.md進行編輯，並更新 API 參考版本號。例如--- title: v1.17 --- [Kubernetes API v1.17](/docs/reference/generated/kubernetes-api/v1.17/)開啟
<web-base>/content/en/docs/reference/_index.md進行編輯，併為最新的 API 參考新增新連結。移除最舊的 API 參考版本。應該有五個指向最新 API 參考的連結。
本地測試 API 參考
釋出 API 參考的本地版本。驗證 本地預覽。
cd <web-base>
git submodule update --init --recursive --depth 1 # if not already done
make container-serve
提交更改
在 <web-base> 中，執行 git add 和 git commit 來提交更改。
將您的更改作為 Pull Request 提交到 kubernetes/website 倉庫。監控您的 Pull Request，並根據需要響應審閱者的評論。繼續監控您的 Pull Request，直到它被合併。