为 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.29.0 生成文档，可以使用以下命令
cd <k8s-base>
git checkout v1.29.0
git pull https://github.com/kubernetes/kubernetes 1.29.0
如果您不需要编辑 kubectl 源代码，请按照设置构建变量的说明进行操作。
编辑 kubectl 源代码
kubectl 命令参考文档是从 kubectl 源代码自动生成的。如果您想更改参考文档，第一步是更改 kubectl 源代码中的一个或多个注释。在您的本地 kubernetes/kubernetes 存储库中进行更改，然后向 github.com/kubernetes/kubernetes 的主分支提交拉取请求。
PR 56673 是一个拉取请求示例，它修复了 kubectl 源代码中的拼写错误。
监控您的拉取请求，并回复审查者的评论。继续监控您的拉取请求，直到它被合并到 kubernetes/kubernetes 存储库的目标分支。
将您的更改挑选到发布分支中
您的更改现在位于主分支中，该分支用于开发下一个 Kubernetes 版本。如果您希望您的更改出现在已发布的 Kubernetes 版本的文档中，则需要建议将您的更改挑选到发布分支中。
例如，假设主分支用于开发 Kubernetes 1.30，并且您希望将您的更改向后移植到 release-1.29 分支。有关如何执行此操作的说明，请参阅提议挑选。
监控您的挑选拉取请求，直到它被合并到发布分支中。
注意
提议挑选需要您有权在拉取请求中设置标签和里程碑。如果您没有这些权限，则需要与可以为您设置标签和里程碑的人员合作。设置构建变量
转到 <rdocs-base>。在您的命令行上，设置以下环境变量。
- 将
K8S_ROOT设置为<k8s-base>。 - 将
K8S_WEBROOT设置为<web-base>。 - 将
K8S_RELEASE设置为您要构建的文档版本。例如，如果您要为 Kubernetes 1.29 构建文档，请将K8S_RELEASE设置为 1.29。
例如
export K8S_WEBROOT=$GOPATH/src/github.com/<your-username>/website
export K8S_ROOT=$GOPATH/src/k8s.io/kubernetes
export K8S_RELEASE=1.29
创建版本化目录
createversiondirs 构建目标创建一个版本化目录，并将 kubectl 参考配置文件复制到版本化目录。版本化目录名称遵循 v<major>_<minor> 的模式。
在 <rdocs-base> 目录中，运行以下构建目标
cd <rdocs-base>
make createversiondirs
在 k8s.io/kubernetes 中签出一个发布标签
在您的本地 <k8s-base> 存储库中，签出具有您要记录的 Kubernetes 版本的分支。例如，如果您想为 Kubernetes 1.29.0 生成文档，请签出 v1.29 标签。确保您的本地分支是最新的。
cd <k8s-base>
git checkout v1.29.0
git pull https://github.com/kubernetes/kubernetes v1.29.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 存储库创建一个拉取请求。监控您的拉取请求，并根据需要回复审查评论。继续监控您的拉取请求，直到它被合并。
您的拉取请求合并几分钟后，您更新的参考主题将在已发布的文档中可见。