生成 kubectl 命令的參考文件
此頁面顯示如何生成 kubectl 命令參考文件。
注意
本主題展示瞭如何為 kubectl 命令（例如 kubectl apply 和 kubectl taint）生成參考文件。本主題不展示如何生成 kubectl 選項的參考頁面。有關如何生成 kubectl 選項參考頁面的說明，請參閱 生成 Kubernetes 元件和工具的參考頁面。準備工作
要求
您需要一臺執行 Linux 或 macOS 的機器。
您需要安裝以下工具
您的
PATH環境變數必須包含必需的構建工具，例如Go二進位制檔案和python。您需要了解如何向 GitHub 儲存庫建立拉取請求。這包括建立儲存庫的個人分支。有關更多資訊，請參閱 從本地克隆進行工作。
設定本地倉庫
建立本地工作區並設定 GOPATH
mkdir -p $HOME/<workspace>
export GOPATH=$HOME/<workspace>
克隆以下倉庫的本地副本
go get -u github.com/spf13/pflag
go get -u github.com/spf13/cobra
go get -u gopkg.in/yaml.v2
go get -u github.com/kubernetes-sigs/reference-docs
如果還沒有 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
從 $GOPATH/src/k8s.io/kubernetes/vendor/github.com 中刪除 spf13 包
rm -rf $GOPATH/src/k8s.io/kubernetes/vendor/github.com/spf13
kubernetes/kubernetes 倉庫提供了 kubectl 和 kustomize 的原始碼。
確定你的 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>。
在你的本地 k8s.io/kubernetes 倉庫中，檢出你感興趣的分支，並確保它是最新的。例如，如果你想生成 Kubernetes 1.33.0 的文件，可以使用以下命令
cd <k8s-base>
git checkout v1.33.0
git pull https://github.com/kubernetes/kubernetes 1.33.0
如果你不需要編輯 kubectl 原始碼，請按照 設定構建變數 中的說明進行操作。
編輯 kubectl 原始碼
kubectl 命令參考文件是根據 kubectl 原始碼自動生成的。如果你想更改參考文件，第一步是更改 kubectl 原始碼中的一個或多個註釋。在你的本地 kubernetes/kubernetes 倉庫中進行更改，然後向 github.com/kubernetes/kubernetes 的 master 分支提交一個拉取請求。
PR 56673 是一個修復了 kubectl 原始碼中拼寫錯誤的拉取請求示例。
監視你的拉取請求，並回複審稿人的評論。繼續監視你的拉取請求，直到它被合併到 kubernetes/kubernetes 倉庫的目標分支。
將你的更改挑選到釋出分支
你的更改現在已合併到 master 分支，該分支用於開發下一個 Kubernetes 版本。如果你希望你的更改出現在已釋出 Kubernetes 版本的文件中，你需要提議將你的更改挑選（cherry-pick）到釋出分支。
例如，假設 master 分支正在用於開發 Kubernetes 1.34，而你想將你的更改反向移植到 release-1.33 分支。有關如何執行此操作的說明，請參閱 提議挑選（Cherry Pick）。
監視你的挑選（cherry-pick）拉取請求，直到它被合併到釋出分支。
注意
提議挑選（cherry-pick）要求你有權在你的拉取請求中設定標籤和里程碑。如果你沒有這些許可權，你需要與能夠為你設定標籤和里程碑的人合作。設定構建變數
轉到 <rdocs-base> 目錄。在命令列中，設定以下環境變數。
- 將
K8S_ROOT設定為<k8s-base>。 - 將
K8S_WEBROOT設定為<web-base>。 - 將
K8S_RELEASE設定為你想要構建的文件版本。例如，如果你想構建 Kubernetes 1.33 的文件，請將K8S_RELEASE設定為 1.33。
例如
export K8S_WEBROOT=$GOPATH/src/github.com/<your-username>/website
export K8S_ROOT=$GOPATH/src/k8s.io/kubernetes
export K8S_RELEASE=1.33
建立版本化目錄
createversiondirs 構建目標會建立一個版本化目錄，並將 kubectl 參考配置檔案複製到該目錄中。版本化目錄的名稱遵循 v<major>_<minor> 的模式。
在 <rdocs-base> 目錄中，執行以下構建目標
cd <rdocs-base>
make createversiondirs
在 k8s.io/kubernetes 中檢出釋出標籤
在你的本地 <k8s-base> 倉庫中，檢出你想要記錄的 Kubernetes 版本的 ist-release 分支。例如，如果你想生成 Kubernetes 1.33.0 的文件，請檢出 v1.33 標籤。確保你的本地分支是最新的。
cd <k8s-base>
git checkout v1.33.0
git pull https://github.com/kubernetes/kubernetes v1.33.0
執行文件生成程式碼
在你的本地 <rdocs-base> 目錄中，執行 copycli 構建目標。命令以 root 使用者身份執行
cd <rdocs-base>
make copycli
copycli 命令會清理臨時構建目錄，生成 kubectl 命令檔案，並將彙總的 kubectl 命令參考 HTML 頁面和資源複製到 <web-base> 目錄。
查詢生成的檔案
驗證這兩個檔案已生成
[ -e "<rdocs-base>/gen-kubectldocs/generators/build/index.html" ] && echo "index.html built" || echo "no index.html"
[ -e "<rdocs-base>/gen-kubectldocs/generators/build/navData.js" ] && echo "navData.js built" || echo "no navData.js"
查詢複製的檔案
驗證所有生成的檔案是否已複製到你的 <web-base> 目錄
cd <web-base>
git status
輸出應包含已修改的檔案
static/docs/reference/generated/kubectl/kubectl-commands.html
static/docs/reference/generated/kubectl/navData.js
輸出可能還包括
static/docs/reference/generated/kubectl/scroll.js
static/docs/reference/generated/kubectl/stylesheet.css
static/docs/reference/generated/kubectl/tabvisibility.js
static/docs/reference/generated/kubectl/node_modules/bootstrap/dist/css/bootstrap.min.css
static/docs/reference/generated/kubectl/node_modules/highlight.js/styles/default.css
static/docs/reference/generated/kubectl/node_modules/jquery.scrollto/jquery.scrollTo.min.js
static/docs/reference/generated/kubectl/node_modules/jquery/dist/jquery.min.js
static/docs/reference/generated/kubectl/node_modules/font-awesome/css/font-awesome.min.css
本地測試文件
在你的本地 <web-base> 目錄中構建 Kubernetes 文件。
cd <web-base>
git submodule update --init --recursive --depth 1 # if not already done
make container-serve
檢視 本地預覽。
在 kubernetes/website 中新增和提交更改
執行 git add 和 git commit 來提交檔案。
建立拉取請求
向 kubernetes/website 倉庫建立拉取請求。監視你的拉取請求，並根據需要回複審閱評論。繼續監視你的拉取請求，直到它被合併。
在你的拉取請求合併幾分鐘後，你更新的參考主題將顯示在 已釋出的文件 中。