diff --git a/content/zh/docs/contribute/generate-ref-docs/kubectl.md b/content/zh/docs/contribute/generate-ref-docs/kubectl.md new file mode 100644 index 0000000000..e9736dbca9 --- /dev/null +++ b/content/zh/docs/contribute/generate-ref-docs/kubectl.md @@ -0,0 +1,473 @@ +--- +title: 为 kubectl 命令集生成参考文档 +content_template: templates/task +--- + + + +{{% capture overview %}} + + + +该页面显示了如何自动生成 `kubectl` 工具提供的命令的参考页面。 + +{{< note >}} + + +本主题展示了如何为 [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/)。 +{{< /note >}} + +{{% /capture %}} + + +{{% capture prerequisites %}} + + + +* 你需要安装 [Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)。 + + + +* 你需要安装 1.9.1 或更高版本的 [Golang](https://golang.org/doc/install), 并在环境变量中设置 `$GOPATH`。 + + + +* 你需要安装 [Docker](https://docs.docker.com/engine/installation/)。 + + + +* 你需要知道如何在一个 GitHub 项目仓库中创建一个 PR。一般来说,这涉及到创建仓库的一个分支。想了解更多信息,请参见[创建一个文档 PR](/docs/home/contribute/create-pull-request/) 和 [GitHub 标准 Fork&PR 工作流](https://gist.github.com/Chaser324/ce0505fbed06b947d962)。 + +{{% /capture %}} + + +{{% capture steps %}} + + + +## 下载三个仓库 + + + +如果你还没有下载过 kubernetes/kubernetes 仓库,现在下载: + +```shell +mkdir $GOPATH/src +cd $GOPATH/src +go get github.com/kubernetes/kubernetes +``` + + + +确定 [kubernetes/kubernetes](https://github.com/kubernetes/kubernetes) 仓库的本地主目录。例如,如果按照前面的步骤来获取该仓库,则主目录是 `$GOPATH/src/github.com/kubernetes/kubernetes`。下文将该目录称为 ``。 + + + +如果你还没有下载过 kubernetes/website 仓库,现在下载: + +```shell +mkdir $GOPATH/src +cd $GOPATH/src +go get github.com/kubernetes/website +``` + + + +确定 [kubernetes/website](https://github.com/kubernetes/website) 仓库的本地主目录。例如,如果按照前面的步骤来获取该仓库,则主目录是 `$GOPATH/src/github.com/kubernetes/website`。下文将该目录称为 ``。 + + + +如果你还没有下载过 kubernetes-incubator/reference-docs 仓库,现在下载: + +```shell +mkdir $GOPATH/src +cd $GOPATH/src +go get github.com/kubernetes-incubator/reference-docs +``` + + + +确定 [kubernetes-incubator/reference-docs](https://github.com/kubernetes-incubator/reference-docs) 仓库的本地主目录。例如,如果按照前面的步骤来获取该仓库,则主目录是 `$GOPATH/src/github.com/kubernetes-incubator/reference-docs`。下文将该目录称为 ``。 + + + +进入 kubernetes/kubernetes 仓库的本地目录,检出感兴趣的分支,并确保它是最新的。例如,如果希望为 Kubernetes 1.9 生成文档,可以使用以下命令: + +```shell +cd +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](https://github.com/kubernetes/kubernetes) 的 master 分支提交 PR。 + + + +[PR 56673](https://github.com/kubernetes/kubernetes/pull/56673/files) 是一个对 kubectl 源码中的笔误进行修复的 PR 示例。 + + + +跟踪你的 PR,并回应评审人的评论。继续跟踪你的 PR,直到它合入到 kubernetes/kubernetes 仓库的 master 分支中。 + + + +## 以 cherry-pick 方式将你的修改合入已发布分支 + + + +你的修改已合入 master 分支中,该分支用于开发下一个 Kubernetes 版本。如果你希望修改部分出现在已发布的 Kubernetes 版本文档中,则需要提议将它们以 cherry-pick 方式合入已发布分支。 + + + +例如,假设 master 分支正用于开发 Kubernetes 1.10 版本,而你希望将修改合入到已发布的 1.9 版本分支。相关的操作指南,请参见 [提议一个 cherry-pick 合入](https://github.com/kubernetes/community/blob/master/contributors/devel/cherry-picks.md)。 + + + +跟踪你的 cherry-pick PR,直到它合入到已发布分支中。 + +{{< note >}} + + +提议一个 cherry-pick 合入,需要你有在 PR 中设置标签和里程碑的权限。如果你没有,你需要与有权限为你设置标签和里程碑的人合作完成。 +{{< /note >}} + + + +## 编辑 Makefile + + + +进入 `` 目录, 打开 `Makefile` 进行编辑: + + + +将 `K8SROOT` 设置为 kubernetes/kubernetes 仓库的本地主目录。将 `WEBROOT` 设置为 kubernetes/website 仓库的本地主目录。将 `MINOR_VERSION` 设置为要构建的文档的副版本号。例如,如果要为 Kubernetes 1.9 版本构建文档,请将 `MINOR_VERSION` 设置为 9。保存并关闭 `Makefile`。 + + + +## 制作 brodocs 镜像 + + + +文档生成代码需要 `pwittrock/brodocs` Docker 镜像。 + + + +该命令用于创建 `pwittrock/brodocs` Docker 镜像。它还尝试将镜像推送到 DockerHub,但是如果该步骤失败也没关系。只要镜像在本地,就可以成功生成代码。 + + +```shell +make brodocs +``` + + + +确认 brodocs 镜像是否存在 + +```shell +docker images +``` + + + +输出显示 `pwittrock/brodocs` 是可用镜像之一: + +```shell +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` 目录: + +```shell +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 用户运行命令: + +```shell +cd +make cli +``` + + + +## 找到生成的文件 + + + +这两个文件是成功构建的主要产物。验证它们是否存在: + +* `/gen-kubectldocs/generators/build/index.html` +* `/gen-kubectldocs/generators/build/navData.js` + + + +## 将文件复制到 kubernetes/website 仓库 + + + +将生成的文件从 kubernetes-incubator/reference-docs 仓库的本地目录复制到 kubernetes/website 仓库的本地目录。 + +```shell +cd +make copycli +``` + + + +## 在 kubernetes/website 中添加和提交修改 + + + +列出生成并准备合入到 `kubernetes/website` 仓库中的文件: + +``` +cd +git status +``` + + + +输出展示了新增和修改的文件。例如,输出可能如下所示: + +```shell +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 合入的几分钟后,你更新的参考主题将出现在[已发布文档](/docs/home/)中。 + + +{{% /capture %}} + +{{% capture whatsnext %}} + + + +* [为 Kubernetes 组件和工具生成参考文档](/docs/home/contribute/generated-reference/kubernetes-components/) +* [为 Kubernetes API 生成参考文档](/docs/home/contribute/generated-reference/kubernetes-api/) +* [为 Kubernetes 联邦 API 生成参考文档](/docs/home/contribute/generated-reference/federation-api/) + +{{% /capture %}} + + +