website/content/zh/docs/contribute/generate-ref-docs/kubectl.md

title, content_template

title	content_template
为 kubectl 命令集生成参考文档	templates/task

{{% capture overview %}}

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

{{< note >}}

本主题展示了如何为 kubectl 命令集 生成参考文档，如 kubectl apply 和 kubectl taint。

本主题没有展示如何生成 kubectl 组件的参考页面。相关说明请参见为 Kubernetes 组件和工具生成参考页面。 {{< /note >}}

{{% /capture %}}

{{% capture prerequisites %}}

• 你需要安装 Git。

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

• 你需要安装 Docker。

• 你需要知道如何在一个 GitHub 项目仓库中创建一个 PR。一般来说，这涉及到创建仓库的一个分支。想了解更多信息，请参见创建一个文档 PR 和 GitHub 标准 Fork&PR 工作流。

{{% /capture %}}

{{% capture steps %}}

下载三个仓库

如果你还没有下载过 kubernetes/kubernetes 仓库，现在下载：

mkdir $GOPATH/src
cd $GOPATH/src
go get github.com/kubernetes/kubernetes

确定 kubernetes/kubernetes 仓库的本地主目录。例如，如果按照前面的步骤来获取该仓库，则主目录是 $GOPATH/src/github.com/kubernetes/kubernetes。下文将该目录称为 <k8s-base>。

如果你还没有下载过 kubernetes/website 仓库，现在下载：

mkdir $GOPATH/src
cd $GOPATH/src
go get github.com/kubernetes/website

确定 kubernetes/website 仓库的本地主目录。例如，如果按照前面的步骤来获取该仓库，则主目录是 $GOPATH/src/github.com/kubernetes/website。下文将该目录称为 <web-base>。

如果你还没有下载过 kubernetes-incubator/reference-docs 仓库，现在下载：

mkdir $GOPATH/src
cd $GOPATH/src
go get github.com/kubernetes-incubator/reference-docs

确定 kubernetes-incubator/reference-docs 仓库的本地主目录。例如，如果按照前面的步骤来获取该仓库，则主目录是 $GOPATH/src/github.com/kubernetes-incubator/reference-docs。下文将该目录称为 <rdocs-base>。

进入 kubernetes/kubernetes 仓库的本地目录，检出感兴趣的分支，并确保它是最新的。例如，如果希望为 Kubernetes 1.9 生成文档，可以使用以下命令：

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

编辑 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.9 版本分支。相关的操作指南，请参见 提议一个 cherry-pick 合入。

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

{{< note >}}

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

编辑 Makefile

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

将 K8SROOT 设置为 kubernetes/kubernetes 仓库的本地主目录。将 WEBROOT 设置为 kubernetes/website 仓库的本地主目录。将 MINOR_VERSION 设置为要构建的文档的副版本号。例如，如果要为 Kubernetes 1.9 版本构建文档，请将 MINOR_VERSION 设置为 9。保存并关闭 Makefile。

制作 brodocs 镜像

文档生成代码需要 pwittrock/brodocs Docker 镜像。

该命令用于创建 pwittrock/brodocs Docker 镜像。它还尝试将镜像推送到 DockerHub，但是如果该步骤失败也没关系。只要镜像在本地，就可以成功生成代码。

make brodocs

确认 brodocs 镜像是否存在：

docker images

输出显示 pwittrock/brodocs 是可用镜像之一：

REPOSITORY          TAG                 IMAGE ID            CREATED             SIZE
pwittrock/brodocs   latest              999d34a50d56        5 weeks ago         714MB

创建版本目录

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

mkdir gen-kubectldocs/generators/v1_9
cp -r gen-kubectldocs/generators/v1_8/* gen-kubectldocs/generators/v1_9

从 kubernetes/kubernetes 检出一个分支

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

运行文档生成代码

在 kubernetes-incubator/reference-docs 仓库的本地目录中，构建并运行文档生成代码。你可能需要以 root 用户运行命令：

cd <rdocs-base>
make cli

找到生成的文件

这两个文件是成功构建的主要产物。验证它们是否存在：

• <rdocs-base>/gen-kubectldocs/generators/build/index.html
• <rdocs-base>/gen-kubectldocs/generators/build/navData.js

将文件复制到 kubernetes/website 仓库

将生成的文件从 kubernetes-incubator/reference-docs 仓库的本地目录复制到 kubernetes/website 仓库的本地目录。

cd <rdocs-base>
make copycli

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

列出生成并准备合入到 kubernetes/website 仓库中的文件：

cd <web-base>
git status

输出展示了新增和修改的文件。例如，输出可能如下所示：

modified: docs/reference/generated/kubectl/kubectl-commands.html
modified: docs/reference/generated/kubectl/navData.js

运行 git add 和 git commit 将提交上述文件。

创建 PR

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

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

{{% /capture %}}

{{% capture whatsnext %}}

• 为 Kubernetes 组件和工具生成参考文档
• 为 Kubernetes API 生成参考文档
• 为 Kubernetes 联邦 API 生成参考文档

{{% /capture %}}