Edit This Page

为 kubectl 命令集生成参考文档

该页面显示了如何自动生成 kubectl 工具提供的命令的参考页面。

注意： 本主题展示了如何为 [kubectl 命令集](/docs/reference/generated/kubectl/kubectl-commands) 生成参考文档，如 [kubectl apply](/docs/reference/generated/kubectl/kubectl-commands#apply) 和 [kubectl taint](/docs/reference/generated/kubectl/kubectl-commands#taint)。 本主题没有展示如何生成 [kubectl](/docs/reference/generated/kubectl/kubectl/) 组件的参考页面。相关说明请参见[为 Kubernetes 组件和工具生成参考页面](/docs/home/contribute/generated-reference/kubernetes-components/)。

准备开始

  • 你需要安装 Git。
  • 你需要安装 1.9.1 或更高版本的 Golang, 并在环境变量中设置 $GOPATH。

设置本地仓库

创建本地工作区并设置您的 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 kubernetes-incubator/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-incubator/reference-docs 仓库的本地主目录。例如，如果按照前面的步骤来获取该仓库，则主目录是 $GOPATH/src/github.com/kubernetes-incubator/reference-docs。下文将该目录称为 <rdocs-base>。

在您当地的 k8s.io/kubernetes 仓库中，检查感兴趣的分支并确保它是最新的。例如，如果您想要生成 Kubernetes 1.15 的文档，您可以使用以下命令：

cd <k8s-base>
git checkout release-1.15
git pull https://github.com/kubernetes/kubernetes release-1.15

如果不需要编辑 kubectl 源码，请按照说明编辑 Makefile。

编辑 kubectl 源码

kubectl 命令集的参考文档是基于 kubectl 源码自动生成的。如果想要修改参考文档，可以从修改 kubectl 源码中的一个或多个注释开始。在本地 kubernetes/kubernetes 仓库中进行修改，然后向 github.com/kubernetes/kubernetes 的 master 分支提交 PR。

PR 56673 是一个对 kubectl 源码中的笔误进行修复的 PR 示例。

跟踪你的 PR，并回应评审人的评论。继续跟踪你的 PR，直到它合入到 kubernetes/kubernetes 仓库的 master 分支中。

以 cherry-pick 方式将你的修改合入已发布分支

你的修改已合入 master 分支中，该分支用于开发下一个 Kubernetes 版本。如果你希望修改部分出现在已发布的 Kubernetes 版本文档中，则需要提议将它们以 cherry-pick 方式合入已发布分支。

例如，假设 master 分支正用于开发 Kubernetes 1.10 版本，而你希望将修改合入到已发布的 1.15 版本分支。相关的操作指南，请参见 提议一个 cherry-pick 合入。

跟踪你的 cherry-pick PR，直到它合入到已发布分支中。

注意： 提议一个 cherry-pick 合入，需要你有在 PR 中设置标签和里程碑的权限。如果你没有，你需要与有权限为你设置标签和里程碑的人合作完成。

编辑 Makefile

进入 <rdocs-base> 目录, 打开 Makefile 进行编辑：

  • 设置 K8SROOT 为 <k8s-base>。
  • 设置 WEBROOT 为 <web-base>。
  • 设置 MINOR_VERSION 为要构建的文档的次要版本。例如，如果您想为 Kubernetes 1.15 构建文档，请将 MINOR_VERSION 设置为 15。保存并关闭 Makefile 文件。

例如，更新以下变量：

WEBROOT=$(GOPATH)/src/github.com/<your-username>/website
K8SROOT=$(GOPATH)/src/k8s.io/kubernetes
MINOR_VERSION=15

创建版本目录

版本目录是 kubectl 命令集构建的临时区域。该目录中的 YAML 文件用于创建 kubectl 命令集参考的结构和导航。

在 gen-kubectldocs/generators 目录中，如果你还没有一个名为 v1_MINOR_VERSION 的目录，那么现在通过复制前一版本的目录来创建一个。例如，假设你想要为 Kubernetes 1.15 版本生成文档，但是还没有 v1_15 目录，这时可以通过运行以下命令来创建并填充 v1_15 目录：

cd <k8s-base>
git checkout release-1.15
git pull https://github.com/kubernetes/kubernetes release-1.15

从 kubernetes/kubernetes 检出一个分支

在本地 仓库中，检出你想要生成文档的、包含 Kubernetes 版本的分支。例如，如果希望为 Kubernetes 1.15 版本生成文档，请检出 1.15 分支。确保本地分支是最新的。

cd <k8s-base>
git checkout release-1.15
git pull https://github.com/kubernetes/kubernetes release-1.15

运行文档生成代码

在 kubernetes-incubator/reference-docs 仓库的本地目录中，构建并运行 kubectl 命令集参数生成代码。你可能需要以 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>
make docker-serve

查看本地预览。

在 kubernetes/website 中添加和提交更改

运行 git add 和 git commit 提交修改文件。

创建 PR

对 kubernetes/website 仓库创建 PR。跟踪你的 PR，并根据需要回应评审人的评论。继续跟踪你的 PR，直到它被合入。

在 PR 合入的几分钟后，你更新的参考主题将出现在已发布文档中。

接下来