diff --git a/content/zh/docs/contribute/generate-ref-docs/_index.md b/content/zh/docs/contribute/generate-ref-docs/_index.md index ac5f61a40f..7afd3743f5 100644 --- a/content/zh/docs/contribute/generate-ref-docs/_index.md +++ b/content/zh/docs/contribute/generate-ref-docs/_index.md @@ -5,17 +5,22 @@ weight: 80 --- -许多 Kubernetes 参考文档都是使用脚本从 Kubernetes 源代码生成的。本节的主题是如何生成这种类型的文档。 +本节的主题是描述如何生成 Kubernetes 参考指南。 +要生成参考文档，请参考下面的指南： + +* [生成参考文档快速入门](/docs/contribute/generate-ref-docs/quickstart/) + diff --git a/content/zh/docs/contribute/generate-ref-docs/contribute-upstream.md b/content/zh/docs/contribute/generate-ref-docs/contribute-upstream.md index f71871b296..4bfa40f0a8 100644 --- a/content/zh/docs/contribute/generate-ref-docs/contribute-upstream.md +++ b/content/zh/docs/contribute/generate-ref-docs/contribute-upstream.md @@ -1,12 +1,12 @@ --- title: 为上游 Kubernetes 代码库做出贡献 content_type: task +weight: 20 --- @@ -16,93 +16,83 @@ This page shows how to contribute to the upstream kubernetes/kubernetes project to fix bugs found in the Kubernetes API documentation or the `kube-*` components such as `kube-apiserver`, `kube-controller-manager`, etc. --> -此页面描述如何为上游 kubernetes/kubernetes 项目做出贡献，如修复 Kubernetes API 文档或 `kube-*` 组件（例如 kube-apiserver、kube-controller-manager 等）中发现的错误。 +此页面描述如何为上游 `kubernetes/kubernetes` 项目做出贡献，如修复 Kubernetes API +文档或 Kubernetes 组件（例如 `kubeadm`、`kube-apiserver`、`kube-controller-manager` 等） +中发现的错误。 -相反，如果您想从上游代码重新生成 Kubernetes API 或 `kube-*` 组件的参考文档。请参考以下说明： - +如果您仅想从上游代码重新生成 Kubernetes API 或 `kube-*` 组件的参考文档。请参考以下说明： + - [生成 Kubernetes API 的参考文档](/docs/contribute/generate-ref-docs/kubernetes-api/) - [生成 Kubernetes 组件和工具的参考文档](/docs/contribute/generate-ref-docs/kubernetes-components/) - - - ## {{% heading "prerequisites" %}} - -您需要安装以下工具： +- 你需要安装以下工具： + + - [Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) + - [Golang](https://golang.org/doc/install) 的 1.13 版本或更高 + - [Docker](https://docs.docker.com/engine/installation/) + - [etcd](https://github.com/coreos/etcd/) -* [Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) -* [Golang](https://golang.org/doc/install) Go 版本大于 1.9.1 -* [Docker](https://docs.docker.com/engine/installation/) -* [etcd](https://github.com/coreos/etcd/) +- 你必须设置 `GOPATH` 环境变量，并且 `etcd` 的位置必须在 `PATH` 环境变量中。 -必须设置 $GOPATH 环境变量，并且 `etcd` 的位置必须在 $PATH 环境变量中。 - - -您需要知道如何创建对 GitHub 代码仓库的拉取请求（Pull Request）。 -通常，这涉及创建代码仓库的分支。要获取更多的信息请参考[创建 PR](https://help.github.com/articles/creating-a-pull-request/) 和 -[GitHub 标准 Fork 和 PR 工作流程](https://gist.github.com/Chaser324/ce0505fbed06b947d962)。 - - - - +- 您需要知道如何创建对 GitHub 代码仓库的拉取请求（Pull Request）。 + 通常，这涉及创建代码仓库的派生副本。 + 要获取更多的信息请参考[创建 PR](https://help.github.com/articles/creating-a-pull-request/) 和 + [GitHub 标准派生和 PR 工作流程](https://gist.github.com/Chaser324/ce0505fbed06b947d962)。 -## 基本原则 - -Kubernetes API 和 `kube-*` 组件（例如 `kube-apiserver`、`kube-controller-manager`）的参考文档是根据[上游 Kubernetes](https://github.com/kubernetes/kubernetes/) 中的源代码自动生成的。 - +## 基本说明 + +Kubernetes API 和 `kube-*` 组件（例如 `kube-apiserver`、`kube-controller-manager`）的参考文档 +是根据[上游 Kubernetes](https://github.com/kubernetes/kubernetes/) 中的源代码自动生成的。 + 当您在生成的文档中看到错误时，您可能需要考虑创建一个 PR 用来在上游项目中对其进行修复。 ## 克隆 Kubernetes 代码仓库 - -如果您还没有 kubernetes/kubernetes 代码仓库，请立即参照下列命令获取： +如果您还没有 kubernetes/kubernetes 代码仓库，请参照下列命令获取： ```shell mkdir $GOPATH/src @@ -117,9 +107,10 @@ For example, if you followed the preceding step to get the repository, your base directory is `$GOPATH/src/github.com/kubernetes/kubernetes.` The remaining steps refer to your base directory as ``. --> -确定您的 [kubernetes/kubernetes](https://github.com/kubernetes/kubernetes) 代码仓库克隆的基本目录。 -例如，如果按照前面的步骤获取代码仓库，则您的基本目录为 `$GOPATH/src/github.com/kubernetes/kubernetes`。 -接下来其余步骤将您的基本目录称为 ``。 +确定您的 [kubernetes/kubernetes](https://github.com/kubernetes/kubernetes) 代码仓库克隆的根目录。 +例如，如果按照前面的步骤获取代码仓库，则你的根目录为 `$GOPATH/src/github.com/kubernetes/kubernetes`。 +接下来其余步骤将你的根目录称为 ``。 + -确定您的 [kubernetes-sigs/reference-docs](https://github.com/kubernetes-sigs/reference-docs) 代码仓库克隆的基本目录。 -例如，如果按照前面的步骤获取代码仓库，则您的基本目录为 `$GOPATH/src/github.com/kubernetes-sigs/reference-docs`。 -接下来其余步骤将您的基本目录称为 ``。 +确定您的 [kubernetes-sigs/reference-docs](https://github.com/kubernetes-sigs/reference-docs) +代码仓库克隆的根目录。 +例如，如果按照前面的步骤获取代码仓库，则你的根目录为 +`$GOPATH/src/github.com/kubernetes-sigs/reference-docs`。 +接下来其余步骤将你的根目录称为 ``。 -## 编辑 Kubernetes 源代码 - -Kubernetes API 参考文档是根据 OpenAPI 规范自动生成的，该规范是从 Kubernetes 源代码生成的。如果要更改 API 参考文档，第一步是更改 Kubernetes 源代码中的一个或多个注释。 +## 编辑 Kubernetes 源代码 + +Kubernetes API 参考文档是根据 OpenAPI 规范自动生成的，该规范是从 Kubernetes 源代码生成的。 +如果要更改 API 参考文档，第一步是更改 Kubernetes 源代码中的一个或多个注释。 -### 更改上游 Kubernetes 源代码 - +### 更改上游 Kubernetes 源代码 + {{< note >}} -以下步骤仅作为示例，不是一般步骤，具体情况因您而异。 +以下步骤仅作为示例，不是通用步骤，具体情况因环境而异。 {{< /note >}} -以下在 Kubernetes 源代码中编辑注释的示例。 - -在您本地的 kubernetes/kubernetes 代码仓库中，切换出本地 master 分支，并确保它是最新的： +以下在 Kubernetes 源代码中编辑注释的示例。 + +在您本地的 kubernetes/kubernetes 代码仓库中，检出 master 分支，并确保它是最新的： ```shell cd @@ -184,19 +175,18 @@ git pull https://github.com/kubernetes/kubernetes master -假设 master 分支中的此源文件的拼写错误为 "atmost"： +假设 master 分支中的下面源文件中包含拼写错误 "atmost"： [kubernetes/kubernetes/staging/src/k8s.io/api/apps/v1/types.go](https://github.com/kubernetes/kubernetes/blob/master/staging/src/k8s.io/api/apps/v1/types.go) -在您的本地环境中，打开 `types.go` 文件，然后将 "atmost" 更改为 "at most"。 - -以下命令查看您已更改的文件： +在你的本地环境中，打开 `types.go` 文件，然后将 "atmost" 更改为 "at most"。 + +以下命令验证你已经更改了文件： ```shell git status @@ -216,23 +206,22 @@ On branch master -### 提交已编辑的文件 - -运行 `git add` 和 `git commit` 命令提交到目前为止所做的更改。在下一步中，您将进行第二次提交，将更改分成两个提交很重要。 +### 提交已编辑的文件 + +运行 `git add` 和 `git commit` 命令提交到目前为止所做的更改。 +在下一步中，您将进行第二次提交，将更改分成两个提交很重要。 ### 生成 OpenAPI 规范和相关文件 - 进入 `` 目录并运行以下脚本： ```shell @@ -242,12 +231,10 @@ hack/update-generated-protobuf.sh hack/update-api-reference-docs.sh ``` - -运行 `git status` 命令查看生成的东西。 + +运行 `git status` 命令查看生成的文件。 -```shell +```none On branch master ... modified: api/openapi-spec/swagger.json @@ -264,14 +251,16 @@ For example, you could run `git diff -a api/openapi-spec/swagger.json`. This is important, because `swagger.json` is the input to the second stage of the doc generation process. --> -查看 `api/openapi-spec/swagger.json` 的内容，以确保 typo 已经被修正。例如，您可以运行 `git diff -a api/openapi-spec/swagger.json` 命令。这很重要，因为 `swagger.json` 是文档生成过程中第二阶段的输入。 +查看 `api/openapi-spec/swagger.json` 的内容，以确保拼写错误已经被修正。 +例如，您可以运行 `git diff -a api/openapi-spec/swagger.json` 命令。 +这很重要，因为 `swagger.json` 是文档生成过程中第二阶段的输入。 -运行 `git add` 和 `git commit` 命令来提交您的更改。现在您有两个提交： +运行 `git add` 和 `git commit` 命令来提交您的更改。现在您有两个提交（commits）： 一种包含编辑的 `types.go` 文件，另一种包含生成的 OpenAPI 规范和相关文件。 将这两个提交分开独立。也就是说，不要 squash 您的提交。 @@ -283,13 +272,16 @@ master branch of the Monitor your pull request, and respond to reviewer comments as needed. Continue to monitor your pull request until it is merged. --> -将您的更改作为 [PR](https://help.github.com/articles/creating-a-pull-request/) 提交到 [kubernetes/kubernetes](https://github.com/kubernetes/kubernetes) 代码仓库的 master 分支。关注您的 PR，并根据需要回复 reviewer 的评论。继续关注您的 PR，直到 PR 被合并为止。 +将您的更改作为 [PR](https://help.github.com/articles/creating-a-pull-request/) +提交到 [kubernetes/kubernetes](https://github.com/kubernetes/kubernetes) 代码仓库的 master 分支。 +关注您的 PR，并根据需要回复 reviewer 的评论。继续关注您的 PR，直到 PR 被合并为止。 -[PR 57758](https://github.com/kubernetes/kubernetes/pull/57758) 是修复 Kubernetes 源代码中的拼写错误的拉取请求的示例。 +[PR 57758](https://github.com/kubernetes/kubernetes/pull/57758) 是修复 Kubernetes +源代码中的拼写错误的拉取请求的示例。 {{< note >}} -确定要更改的正确源文件可能很棘手。在前面的示例中，官方的源文件位于 `kubernetes/kubernetes` 代码仓库的 `staging` 目录中。但是根据您的情况，`staging` 目录可能不是找到官方源文件的地方。根据指导原则，请检查 [kubernetes/kubernetes](https://github.com/kubernetes/kubernetes/tree/master/staging) 代码仓库和相关代码仓库（例如 [kubernetes/apiserver](https://github.com/kubernetes/apiserver/blob/master/README.md)）中的 `README` 文件。 +确定要更改的正确源文件可能很棘手。在前面的示例中，官方的源文件位于 `kubernetes/kubernetes` +代码仓库的 `staging` 目录中。但是根据您的情况，`staging` 目录可能不是找到官方源文件的地方。 +如果需要帮助，请阅读 +[kubernetes/kubernetes](https://github.com/kubernetes/kubernetes/tree/master/staging) +代码仓库和相关代码仓库 +（例如 [kubernetes/apiserver](https://github.com/kubernetes/apiserver/blob/master/README.md)） +中的 `README` 文件。 {{< /note >}} -### Cherry Pick 将您的提交纳入发布分支 - -在上一节中，您在 master 分支中编辑了一个文件，然后运行了脚本用来生成 OpenAPI 规范和相关文件。然后将您的更改提交到 kubernetes/kubernetes 代码仓库的 master 分支的 pull request 中。 现在，需要将您的更改反向移植到已经 release 的分支。例如，假设使用 master 分支来开发 Kubernetes 1.10 版，并且您想将更改反向移植到 release-1.9 分支。 +### 将你的提交 Cherrypick 到发布分支 + +在上一节中，你在 master 分支中编辑了一个文件，然后运行了脚本用来生成 OpenAPI 规范和相关文件。 +然后用 PR 将你的更改提交到 kubernetes/kubernetes 代码仓库的 master 分支中。 +现在，需要将你的更改反向移植到已经发布的分支。 +例如，假设 master 分支被用来开发 Kubernetes 1.10 版，并且你想将更改反向移植到 release-1.9 分支。 -回想一下，您的 pull request 有两个提交：一个用于编辑 `types.go`，一个用于由脚本生成的文件。下一步的目的是对您的第一次提交 cherry pick 到 release-1.9 分支。这个想法是 cherry pick 编辑了 types.go 的提交，但不是具有运行脚本结果的提交。有关说明，请参见[提出 Cherry Pick](https://git.k8s.io/community/contributors/devel/sig-release/cherry-picks.md)。 +回想一下，您的 PR 有两个提交：一个用于编辑 `types.go`，一个用于由脚本生成的文件。 +下一步是将你的第一次提交 cherrypick 到 release-1.9 分支。这样做的原因是仅 cherrypick 编辑了 types.go 的提交， +而不是具有脚本运行结果的提交。 +有关说明，请参见[提出 Cherry Pick](https://git.k8s.io/community/contributors/devel/sig-release/cherry-picks.md)。 {{< note >}} -提出 cherry pick 要求您有权在 pull request 中设置标签和里程碑。如果您没有这些权限，则需要与可以为您设置标签和里程碑的人员合作。 +提出 Cherry Pick 要求你有权在 PR 中设置标签和里程碑。如果您没有这些权限， +则需要与可以为你设置标签和里程碑的人员合作。 {{< /note >}} -当您提出一个 pull request，希望将您的一个提交 cherry pick 到 release-1.9 分支中时，下一步是在本地环境的 release-1.9 分支中运行这些脚本。 +当你发起 PR 将你的一个提交 cherry pick 到 release-1.9 分支中时，下一步是在本地环境的 release-1.9 +分支中运行如下脚本。 ```shell hack/update-generated-swagger-docs.sh @@ -354,7 +359,8 @@ hack/update-api-reference-docs.sh Now add a commit to your cherry-pick pull request that has the recently generated OpenAPI spec and related files. Monitor your pull request until it gets merged into the release-1.9 branch. --> -现在将提交添加到您的 Cherry-pick pull request 中，该请求具有最近生成的 OpenAPI 规范和相关文件。关注您的 pull request 请求，直到其合并到 release-1.9 分支中为止。 +现在将提交添加到您的 Cherry-Pick PR 中，该 PR 中包含最新生成的 OpenAPI 规范和相关文件。 +关注你的 PR，直到其合并到 release-1.9 分支中为止。 -此时，master 分支和 release-1.9 分支都具有更新的 `types.go` 文件和一组生成的文件，这些文件反映了您对 `types.go` 所做的更改。请注意，生成的 OpenAPI 规范和其他 release-1.9 分支中生成的文件不一定与 master 分支中生成的文件相同。release-1.9 分支中生成的文件仅包含来自 Kubernetes 1.9 的 API 元素。master 分支中生成的文件可能包含不在 1.9 中但正在为 1.10 开发的 API 元素。 - +此时，master 分支和 release-1.9 分支都具有更新的 `types.go` 文件和一组生成的文件， +这些文件反映了对 `types.go` 所做的更改。 +请注意，生成的 OpenAPI 规范和其他 release-1.9 分支中生成的文件不一定与 master 分支中生成的文件相同。 +release-1.9 分支中生成的文件仅包含来自 Kubernetes 1.9 的 API 元素。 +master 分支中生成的文件可能包含不在 1.9 中但正在为 1.10 开发的 API 元素。 -## 生成已发布的参考文档 - -上一节显示了如何编辑源文件然后生成多个文件，包括在 `kubernetes/kubernetes` 代码仓库中的 `api/openapi-spec/swagger.json`。 -`swagger.json` 文件是 OpenAPI 定义文件，可用于生成 API 参考文档。 +## 生成已发布的参考文档 + +上一节显示了如何编辑源文件然后生成多个文件，包括在 `kubernetes/kubernetes` 代码仓库中的 +`api/openapi-spec/swagger.json`。`swagger.json` 文件是 OpenAPI 定义文件，可用于生成 API 参考文档。 -现在，您可以按照[生成 Kubernetes API 的参考文档](/docs/contribute/generate-ref-docs/kubernetes-api/)指南来生成 +现在，您可以按照 +[生成 Kubernetes API 的参考文档](/docs/contribute/generate-ref-docs/kubernetes-api/) +指南来生成 [已发布的 Kubernetes API 参考文档](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/)。 - - ## {{% heading "whatsnext" %}} - -该页面显示了如何自动生成 `kubectl` 工具提供的命令的参考页面。 +本页面描述了如何生成 `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 >}} +本主题描述了如何为 [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 >}} - - - ## {{% heading "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)。 - - - +{{< include "prerequisites-ref-docs.md" >}} -## 设置本地仓库 - -创建本地工作区并设置您的 `GOPATH`。 +## 配置本地仓库 + +创建本地工作区并设置你的 `GOPATH`。 ```shell mkdir -p $HOME/ - export GOPATH=$HOME/ ``` - + 获取以下仓库的本地克隆： ```shell @@ -113,16 +72,14 @@ go get -u kubernetes-incubator/reference-docs -如果您还没有下载过 `kubernetes/website` 仓库，现在下载： +如果您还没有获取过 `kubernetes/website` 仓库，现在获取之： ```shell git clone https://github.com//website $GOPATH/src/github.com//website ``` - -克隆下载 kubernetes/kubernetes 仓库，并作为 k8s.io/kubernetes： + +克隆 kubernetes/kubernetes 仓库作为 k8s.io/kubernetes： ```shell git clone https://github.com/kubernetes/kubernetes $GOPATH/src/k8s.io/kubernetes @@ -131,18 +88,15 @@ git clone https://github.com/kubernetes/kubernetes $GOPATH/src/k8s.io/kubernetes -从 `$GOPATH/src/k8s.io/kubernetes/vendor/github.com` 中卸载 spf13 软件包。 +从 `$GOPATH/src/k8s.io/kubernetes/vendor/github.com` 中移除 spf13 软件包。 ```shell rm -rf $GOPATH/src/k8s.io/kubernetes/vendor/github.com/spf13 ``` - + kubernetes/kubernetes 仓库提供对 kubectl 和 kustomize 源代码的访问。 - -确定 [kubernetes/kubernetes](https://github.com/kubernetes/kubernetes) 仓库的本地主目录。例如，如果按照前面的步骤来获取该仓库，则主目录是 `$GOPATH/src/k8s.io/kubernetes.`。下文将该目录称为 ``。 +* 确定 [kubernetes/kubernetes](https://github.com/kubernetes/kubernetes) 仓库的本地主目录。 + 例如，如果按照前面的步骤来获取该仓库，则主目录是 `$GOPATH/src/k8s.io/kubernetes.`。 + 下文将该目录称为 ``。 -确定 [kubernetes/website](https://github.com/kubernetes/website) 仓库的本地主目录。例如，如果按照前面的步骤来获取该仓库，则主目录是 `$GOPATH/src/github.com//website`。下文将该目录称为 ``。 +* 确定 [kubernetes/website](https://github.com/kubernetes/website) 仓库的本地主目录。 + 例如，如果按照前面的步骤来获取该仓库，则主目录是 `$GOPATH/src/github.com//website`。 + 下文将该目录称为 ``。 -确定 [kubernetes-incubator/reference-docs](https://github.com/kubernetes-incubator/reference-docs) 仓库的本地主目录。例如，如果按照前面的步骤来获取该仓库，则主目录是 `$GOPATH/src/github.com/kubernetes-incubator/reference-docs`。下文将该目录称为 ``。 +* 确定 [kubernetes-sigs/reference-docs](https://github.com/kubernetes-sigs/reference-docs) + 仓库的本地主目录。例如，如果按照前面的步骤来获取该仓库，则主目录是 + `$GOPATH/src/github.com/kubernetes-sigs/reference-docs`。 + 下文将该目录称为 ``。 -在您当地的 k8s.io/kubernetes 仓库中，检查感兴趣的分支并确保它是最新的。例如，如果您想要生成 Kubernetes 1.15 的文档，您可以使用以下命令： +在本地的 k8s.io/kubernetes 仓库中，检出感兴趣的分支并确保它是最新的。例如， +如果你想要生成 Kubernetes 1.17 的文档，可以使用以下命令： ```shell cd -git checkout release-1.15 -git pull https://github.com/kubernetes/kubernetes release-1.15 +git checkout v1.17.0 +git pull https://github.com/kubernetes/kubernetes v1.17.0 ``` -如果不需要编辑 kubectl 源码，请按照说明[编辑 Makefile](#editing-makefile)。 +如果不需要编辑 `kubectl` +源码，请按照说明[配置构建变量](#setting-build-variables)。 -## 编辑 kubectl 源码 - - +## 编辑 kubectl 源码 -kubectl 命令集的参考文档是基于 kubectl 源码自动生成的。如果想要修改参考文档，可以从修改 kubectl 源码中的一个或多个注释开始。在本地 kubernetes/kubernetes 仓库中进行修改，然后向 [github.com/kubernetes/kubernetes](https://github.com/kubernetes/kubernetes) 的 master 分支提交 PR。 +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 分支中。 +[PR 56673](https://github.com/kubernetes/kubernetes/pull/56673/files) 是一个对 kubectl +源码中的笔误进行修复的 PR 示例。 + +跟踪你的 PR，并回应评审人的评论。继续跟踪你的 PR，直到它合入到 kubernetes/kubernetes 仓库的 +master 分支中。 -## 以 cherry-pick 方式将你的修改合入已发布分支 - - +## 以 cherry-pick 方式将你的修改合入已发布分支 -你的修改已合入 master 分支中，该分支用于开发下一个 Kubernetes 版本。如果你希望修改部分出现在已发布的 Kubernetes 版本文档中，则需要提议将它们以 cherry-pick 方式合入已发布分支。 +你的修改已合入 master 分支中，该分支用于开发下一个 Kubernetes 版本。 +如果你希望修改部分出现在已发布的 Kubernetes 版本文档中，则需要提议将它们以 +cherry-pick 方式合入已发布分支。 -例如，假设 master 分支正用于开发 Kubernetes 1.10 版本，而你希望将修改合入到已发布的 1.15 版本分支。相关的操作指南，请参见 [提议一个 cherry-pick 合入](https://git.k8s.io/community/contributors/devel/sig-release/cherry-picks.md)。 - - +例如，假设 master 分支正用于开发 Kubernetes 1.16 版本，而你希望将修改合入到已发布的 1.15 版本分支。 +相关的操作指南，请参见 +[提议一个 cherry-pick](https://git.k8s.io/community/contributors/devel/sig-release/cherry-picks.md)。 + 跟踪你的 cherry-pick PR，直到它合入到已发布分支中。 -{{< note >}} -提议一个 cherry-pick 合入，需要你有在 PR 中设置标签和里程碑的权限。如果你没有，你需要与有权限为你设置标签和里程碑的人合作完成。 +{{< note >}} +提议一个 cherry-pick 需要你有在 PR 中设置标签和里程碑的权限。 +如果你没有，你需要与有权限为你设置标签和里程碑的人合作完成。 {{< /note >}} +## Setting build variables -## 编辑 Makefile - - +## 设置构建变量 {#setting-build-variables} 进入 `` 目录, 打开 `Makefile` 进行编辑： -* 设置 `K8SROOT` 为 ``。 -* 设置 `WEBROOT` 为 ``。 -* 设置 `MINOR_VERSION` 为要构建的文档的次要版本。例如，如果您想为 Kubernetes 1.15 构建文档，请将 `MINOR_VERSION` 设置为 15。保存并关闭 `Makefile` 文件。 +* Set `K8S_ROOT` to ``. +* Set `K8S_WEBROOT` to ``. +* Set `K8S_RELEASE` to the version of the docs you want to build. + For example, if you want to build docs for Kubernetes 1.17, set `K8S_RELEASE` to 1.17. - -例如，更新以下变量： +* 设置 `K8S_ROOT` 为 ``。 +* 设置 `K8S_WEBROOT` 为 ``。 +* 设置 `K8S_RELEASE` 为要构建文档的版本。 + 例如，如果您想为 Kubernetes 1.17 构建文档，请将 `K8S_RELEASE` 设置为 1.17。 + +例如： ``` -WEBROOT=$(GOPATH)/src/github.com//website -K8SROOT=$(GOPATH)/src/k8s.io/kubernetes -MINOR_VERSION=15 +export K8S_WEBROOT=$(GOPATH)/src/github.com//website +export K8S_ROOT=$(GOPATH)/src/k8s.io/kubernetes +export K8S_RELEASE=1.17 ``` ## 创建版本目录 - -版本目录是 kubectl 命令集构建的临时区域。该目录中的 YAML 文件用于创建 kubectl 命令集参考的结构和导航。 +构建目标 `createversiondirs` 会生成一个版本目录并将 kubectl 参考配置文件复制到该目录中。 +版本目录的名字模式为 `v_`。 - - -在 `gen-kubectldocs/generators` 目录中，如果你还没有一个名为 `v1_MINOR_VERSION` 的目录，那么现在通过复制前一版本的目录来创建一个。例如，假设你想要为 Kubernetes 1.15 版本生成文档，但是还没有 `v1_15` 目录，这时可以通过运行以下命令来创建并填充 `v1_15` 目录： +在 `` 目录下，执行下面的命令： ```shell -cd -git checkout release-1.15 -git pull https://github.com/kubernetes/kubernetes release-1.15 +cd +make createversiondirs ``` -## 从 kubernetes/kubernetes 检出一个分支 - - +## 从 kubernetes/kubernetes 检出一个分支 -在本地 仓库中，检出你想要生成文档的、包含 Kubernetes 版本的分支。例如，如果希望为 Kubernetes 1.15 版本生成文档，请检出 1.15 分支。确保本地分支是最新的。 +在本地 `` 仓库中，检出你想要生成文档的、包含 Kubernetes 版本的分支。 +例如，如果希望为 Kubernetes 1.17 版本生成文档，请检出 `v1.17.0` 标记。 +确保本地分支是最新的。 ```shell cd -git checkout release-1.15 -git pull https://github.com/kubernetes/kubernetes release-1.15 +git checkout v1.17.0 +git pull https://github.com/kubernetes/kubernetes v1.17.0 ``` -## 运行文档生成代码 - - +## 运行文档生成代码 -在 kubernetes-incubator/reference-docs 仓库的本地目录中，构建并运行 kubectl 命令集参数生成代码。你可能需要以 root 用户运行命令： +在本地的 `` 目录下，运行 `copycli` 构建目标。此命令以 `root` 账号运行： ```shell cd @@ -361,16 +316,16 @@ make copycli The `copycli` command will clean the staging directories, generate the kubectl command files, and copy the collated kubectl reference HTML page and assets to ``. --> -`copycli` 命令将清理暂存目录，生成 kubectl 命令集文件，并将整理后的 kubectl 参考 HTML 页面和文件复制到 ``。 +`copycli` 命令将清理暂存目录，生成 kubectl 命令文件，并将整理后的 kubectl 参考 HTML 页面和 +文件复制到 ``。 ## 找到生成的文件 - 验证是否已生成以下两个文件： ```shell @@ -380,22 +335,19 @@ Verify that these two files have been generated: ## 找到复制的文件 - -确认所有生成的文件都已复制到您的 ``： +确认所有生成的文件都已复制到你的 ``： ```shell cd git status ``` - + 输出应包括修改后的文件： ``` @@ -403,10 +355,9 @@ static/docs/reference/generated/kubectl/kubectl-commands.html static/docs/reference/generated/kubectl/navData.js ``` - -此外，输出可能显示修改后的文件： + + +此外，输出可能还包含： ``` static/docs/reference/generated/kubectl/scroll.js @@ -421,12 +372,11 @@ static/docs/reference/generated/kubectl/node_modules/font-awesome/css/font-aweso ## 在本地测试文档 - 在本地 `` 中构建 Kubernetes 文档。 ```shell @@ -434,55 +384,44 @@ cd make docker-serve ``` - + 查看[本地预览](https://localhost:1313/docs/reference/generated/kubectl/kubectl-commands/)。 ## 在 kubernetes/website 中添加和提交更改 - 运行 `git add` 和 `git commit` 提交修改文件。 -## 创建 PR - -对 `kubernetes/website` 仓库创建 PR。跟踪你的 PR，并根据需要回应评审人的评论。继续跟踪你的 PR，直到它被合入。 - - +## 创建 PR + +对 `kubernetes/website` 仓库创建 PR。跟踪你的 PR，并根据需要回应评审人的评论。 +继续跟踪你的 PR，直到它被合入。 在 PR 合入的几分钟后，你更新的参考主题将出现在[已发布文档](/docs/home/)中。 - - - ## {{% heading "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/) +* [生成参考文档快速入门](/docs/home/contribute/generate-ref-docs/quickstart/) +* [为 Kubernetes 组件和工具生成参考文档](/docs/home/contribute/generate-ref-docs/kubernetes-components/) +* [为 Kubernetes API 生成参考文档](/docs/home/contribute/generate-ref-docs/kubernetes-api/) diff --git a/content/zh/docs/contribute/generate-ref-docs/kubernetes-api.md b/content/zh/docs/contribute/generate-ref-docs/kubernetes-api.md index c31b9a2909..135f8843ef 100644 --- a/content/zh/docs/contribute/generate-ref-docs/kubernetes-api.md +++ b/content/zh/docs/contribute/generate-ref-docs/kubernetes-api.md @@ -1,21 +1,22 @@ --- title: 为 Kubernetes API 生成参考文档 content_type: task +weight: 50 --- 本页面展示了如何为 Kubernetes API 更新自动生成的参考文档。 -Kubernetes API 参考文档是从 [Kubernetes OpenAPI 规范](https://github.com/kubernetes/kubernetes/blob/master/api/openapi-spec/swagger.json)构建的，而工具是从 [kubernetes-incubator/reference-docs](https://github.com/kubernetes-incubator/reference-docs) 构建的。 - -如果您在生成的文档中发现错误，则需要[将其上游修复](/docs/contribute/generate-ref-docs/contribute-upstream/)。 - -如果您只需要从 [OpenAPI](https://github.com/OAI/OpenAPI-Specification) 规范中重新生成参考文档，请继续阅读此页面。 +Kubernetes API 参考文档是从 +[Kubernetes OpenAPI 规范](https://github.com/kubernetes/kubernetes/blob/master/api/openapi-spec/swagger.json) +构建的，而工具是从 +[kubernetes-sigs/reference-docs](https://github.com/kubernetes-sigs/reference-docs) 构建的。 +如果您在生成的文档中发现错误，则需要[在上游修复](/docs/contribute/generate-ref-docs/contribute-upstream/)。 +如果您只需要从 [OpenAPI](https://github.com/OAI/OpenAPI-Specification) 规范中重新生成参考文档，请继续阅读此页。 ## {{% heading "prerequisites" %}} - - - -你需要安装以下软件： - - - -* [Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) -* 1.9.1 或更高版本的 [Golang](https://golang.org/doc/install) - - -你需要知道如何在一个 GitHub 项目仓库中创建一个 PR。一般来说，这涉及到创建仓库的 fork 分支。想了解更多信息，请参见[创建一个文档 PR](/docs/contribute/start/) 和 [GitHub 标准 Fork & PR 工作流](https://gist.github.com/Chaser324/ce0505fbed06b947d962)。 - - - +{{< include "prerequisites-ref-docs.md" >}} -## 设置本地仓库 - -创建本地工作区并设置您的 `GOPATH`。 +## 配置本地仓库 + +创建本地工作区并设置你的 `GOPATH`。 ```shell mkdir -p $HOME/ - export GOPATH=$HOME/ ``` - + 获取以下仓库的本地克隆： ```shell go get -u github.com/kubernetes-incubator/reference-docs - go get -u github.com/go-openapi/loads go get -u github.com/go-openapi/spec ``` - -如果您还没有下载过 `kubernetes/website` 仓库，现在下载： + +如果你还没有下载过 `kubernetes/website` 仓库，现在下载： ```shell git clone https://github.com//website $GOPATH/src/github.com//website ``` - -克隆下载 kubernetes/kubernetes 仓库，并作为 k8s.io/kubernetes： + +克隆 kubernetes/kubernetes 仓库作为 k8s.io/kubernetes： ```shell git clone https://github.com/kubernetes/kubernetes $GOPATH/src/k8s.io/kubernetes @@ -125,97 +94,91 @@ The remaining steps refer to your base directory as ``. repository is `$GOPATH/src/github.com/kubernetes-incubator/reference-docs.` The remaining steps refer to your base directory as ``. --> -* [kubernetes/kubernetes](https://github.com/kubernetes/kubernetes) 仓库克隆后的基本目录为 `$GOPATH/src/k8s.io/kubernetes`。 -其余后续步骤将您的基本目录称为 ``。 - -* [kubernetes/website](https://github.com/kubernetes/website) 仓库克隆后的基本目录为 `$GOPATH/src/github.com//website`。 -其余后续步骤将您的基本目录称为 ``。 - -* [kubernetes-incubator/reference-docs](https://github.com/kubernetes-incubator/reference-docs) 仓库克隆后的基本目录为 `$GOPATH/src/github.com/kubernetes-incubator/reference-docs`。 -其余后续步骤将您的基本目录称为 ``。 +* [kubernetes/kubernetes](https://github.com/kubernetes/kubernetes) 仓库克隆后的根目录为 + `$GOPATH/src/k8s.io/kubernetes`。 后续步骤将此目录称为 ``。 +* [kubernetes/website](https://github.com/kubernetes/website) 仓库克隆后的根目录为 + `$GOPATH/src/github.com//website`。后续步骤将此目录称为 ``。 +* [kubernetes-sigs/reference-docs](https://github.com/kubernetes-sigs/reference-docs) + 仓库克隆后的基本目录为 `$GOPATH/src/github.com/kubernetes-sigs/reference-docs`。 + 后续步骤将此目录称为 ``。 -## 生成 API 参考文档 - +## 生成 API 参考文档 + 本节说明如何生成[已发布的 Kubernetes API 参考文档](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/)。 -### 修改 Makefile 文件 +### Setting build variables - -进入 `` 目录，然后编辑 `Makefile` 文件： +### 设置构建变量 {#setting-build-variables} -* 设置 `K8SROOT` 为 ``. -* 设置 `WEBROOT` 为 ``. -* 设置 `MINOR_VERSION` 为要构建的文档的次要版本。例如，如果您想为 Kubernetes 1.15 构建文档，请将 `MINOR_VERSION` 设置为 15。保存并关闭 `Makefile` 文件。 +* 设置 `K8S_ROOT` 为 ``. +* 设置 `K8S_WEBROOT` 为 ``. +* 设置 `K8S_RELEASE` 为要构建的文档的版本。 + 例如，如果您想为 Kubernetes 1.17 构建文档，请将 `K8S_RELEASE` 设置为 1.17。 - -例如，更新以下变量： + +例如： ``` -WEBROOT=$(GOPATH)/src/github.com//website -K8SROOT=$(GOPATH)/src/k8s.io/kubernetes -MINOR_VERSION=15 +export K8S_WEBROOT=$(GOPATH)/src/github.com//website +export K8S_ROOT=$(GOPATH)/src/k8s.io/kubernetes +export K8S_RELEASE=1.17 ``` -### 复制 OpenAPI 规范 +### Creating versioned directory and fetching Open API spec - -在 `` 目录中运行以下命令： +### 创建版本目录并复制 OpenAPI 规范 + +构建目标 `updateapispec` 负责创建版本化的构建目录。 +目录创建了之后，从 `` 仓库取回 OpenAPI 规范文件。 +这些步骤确保配置文件的版本和 Kubernetes OpenAPI 规范的版本与发行版本匹配。 +版本化目录的名称形式为 `v_`。 ```shell make updateapispec ``` - -输出显示文件已被复制： - -```shell -cp ~/src/k8s.io/kubernetes/api/openapi-spec/swagger.json gen-apidocs/generators/openapi-spec/swagger.json -``` - ### 构建 API 参考文档 - +构建目标 `copyapi` 会生成 API 参考文档并将所生成文件复制到 +`` 目录中运行以下命令： ```shell -make api +cd +make copyapi ``` - + 验证是否已生成这两个文件： ```shell @@ -223,108 +186,83 @@ Verify that these two files have been generated: [ -e "/gen-apidocs/generators/build/navData.js" ] && echo "navData.js built" || echo "no navData.js" ``` - -### 创建发布文档的目录 - - -在 `` 目录中为生成的 API 参考文件创建目录： - -```shell -mkdir -p /static/docs/reference/generated/kubernetes-api/v1. -mkdir -p /static/docs/reference/generated/kubernetes-api/v1./css -mkdir -p /static/docs/reference/generated/kubernetes-api/v1./fonts -``` - - -## 将生成的文档复制到 kubernetes/website 仓库 - - -在 `` 目录中运行以下命令，将生成的文件复制到本地 kubernetes/website 仓库。 - -```shell -make copyapi -``` - - -进入 kubernetes/website 仓库的本地主目录，并查看已修改的文件： +进入本地 `` 目录，检查哪些文件被更改： ```shell cd git status ``` - -输出显示修改后的文件： + +输出类似于： ``` -static/docs/reference/generated/kubernetes-api/v1.15/css/bootstrap.min.css -static/docs/reference/generated/kubernetes-api/v1.15/css/font-awesome.min.css -static/docs/reference/generated/kubernetes-api/v1.15/css/stylesheet.css -static/docs/reference/generated/kubernetes-api/v1.15/fonts/FontAwesome.otf -static/docs/reference/generated/kubernetes-api/v1.15/fonts/fontawesome-webfont.eot -static/docs/reference/generated/kubernetes-api/v1.15/fonts/fontawesome-webfont.svg -static/docs/reference/generated/kubernetes-api/v1.15/fonts/fontawesome-webfont.ttf -static/docs/reference/generated/kubernetes-api/v1.15/fonts/fontawesome-webfont.woff -static/docs/reference/generated/kubernetes-api/v1.15/fonts/fontawesome-webfont.woff2 -static/docs/reference/generated/kubernetes-api/v1.15/index.html -static/docs/reference/generated/kubernetes-api/v1.15/jquery.scrollTo.min.js -static/docs/reference/generated/kubernetes-api/v1.15/navData.js -static/docs/reference/generated/kubernetes-api/v1.15/scroll.js +static/docs/reference/generated/kubernetes-api/{{< param "version" >}}/css/bootstrap.min.css +static/docs/reference/generated/kubernetes-api/{{< param "version" >}}/css/font-awesome.min.css +static/docs/reference/generated/kubernetes-api/{{< param "version" >}}/css/stylesheet.css +static/docs/reference/generated/kubernetes-api/{{< param "version" >}}/fonts/FontAwesome.otf +static/docs/reference/generated/kubernetes-api/{{< param "version" >}}/fonts/fontawesome-webfont.eot +static/docs/reference/generated/kubernetes-api/{{< param "version" >}}/fonts/fontawesome-webfont.svg +static/docs/reference/generated/kubernetes-api/{{< param "version" >}}/fonts/fontawesome-webfont.ttf +static/docs/reference/generated/kubernetes-api/{{< param "version" >}}/fonts/fontawesome-webfont.woff +static/docs/reference/generated/kubernetes-api/{{< param "version" >}}/fonts/fontawesome-webfont.woff2 +static/docs/reference/generated/kubernetes-api/{{< param "version" >}}/index.html +static/docs/reference/generated/kubernetes-api/{{< param "version" >}}/js/jquery.scrollTo.min.js +static/docs/reference/generated/kubernetes-api/{{< param "version" >}}/js/navData.js +static/docs/reference/generated/kubernetes-api/{{< param "version" >}}/js/scroll.js ``` ## 更新 API 参考索引页面 +在为新发行版本生成参考文档时，需要更新下面的文件，使之包含新的版本号： +`/content/en/docs/reference/kubernetes-api/api-index.md`。 - -* 打开 `/content/en/docs/reference/kubernetes-api/index.md` 文件进行编辑，并且更新 API 参考版本号。例如： +* 打开并编辑 `/content/en/docs/reference/kubernetes-api/api-index.md`， + API 参考的版本号。例如： ``` - --- - title: v1.15 - --- - - [Kubernetes API v1.15](/docs/reference/generated/kubernetes-api/v1.15/) + title: v1.17 + [Kubernetes API v1.17](/docs/reference/generated/kubernetes-api/v1.17/) ``` - - -* 打开 `/content/en/docs/reference/_index.md` 文件进行编辑，并添加新链接以获取最新的 API 参考。移除最旧的 API 参考版本。应该有五个指向最新 API 参考的链接。 - +* 打开编辑 `/content/en/docs/reference/_index.md`，添加指向最新 API 参考 + 的链接，删除最老的 API 版本。 + 通常保留最近的五个版本的 API 参考的链接。 -## 在本地测试 API 参考 - +## 在本地测试 API 参考 + 发布 API 参考的本地版本。 -验证 [本地预览](http://localhost:1313/docs/reference/generated/kubernetes-api/v1.15/)。 +检查[本地预览](http://localhost:1313/docs/reference/generated/kubernetes-api/v1.15/)。 ```shell cd @@ -333,11 +271,11 @@ make docker-serve ## 提交更改 - 在 `` 中运行 `git add` 和 `git commit` 来提交更改。 -将您的更改[创建 PR](/docs/contribute/start/) 提交到 [kubernetes/website](https://github.com/kubernetes/website) 仓库。监视您提交的 PR，并根据需要回复 reviewer 的评论。继续监视您的 PR，直到合并为止。 - - +基于你所生成的更改[创建 PR](/docs/contribute/start/)， +提交到 [kubernetes/website](https://github.com/kubernetes/website) 仓库。 +监视您提交的 PR，并根据需要回复 reviewer 的评论。继续监视您的 PR，直到合并为止。 ## {{% heading "whatsnext" %}} - -* [为 Kubernetes 组件和工具生成参考文档](/docs/home/contribute/generated-reference/kubernetes-components/) -* [为 kubectl 命令集生成参考文档](/docs/home/contribute/generated-reference/kubectl/) -* [为 Kubernetes 联邦 API 生成参考文档](/docs/home/contribute/generated-reference/federation-api/) +* [生成参考文档快速入门](/docs/home/contribute/generate-ref-docs/quickstart/) +* [为 Kubernetes 组件和工具生成参考文档](/docs/home/contribute/generate-ref-docs/kubernetes-components/) +* [为 kubectl 命令集生成参考文档](/docs/home/contribute/generate-ref-docs/kubectl/) diff --git a/content/zh/docs/contribute/generate-ref-docs/kubernetes-components.md b/content/zh/docs/contribute/generate-ref-docs/kubernetes-components.md index 676575d2cc..95b2794047 100644 --- a/content/zh/docs/contribute/generate-ref-docs/kubernetes-components.md +++ b/content/zh/docs/contribute/generate-ref-docs/kubernetes-components.md @@ -1,413 +1,50 @@ --- -title: 为 Kubernetes 组件和工具生成参考页面 +title: 为 Kubernetes 组件和工具生成参考文档 content_type: task +weight: 120 --- - -本页面展示了如何使用 `update-imported-docs` 工具来为 [Kubernetes](https://github.com/kubernetes/kubernetes) 和 [Federation](https://github.com/kubernetes/federation) 仓库中的工具和组件生成参考文档。 - - +本页面描述如何构造 Kubernetes 组件和工具的参考文档。 ## {{% heading "prerequisites" %}} - - -* 你需要一个运行着 Linux 或 macOS 操作系统的机器。 - - - -* 你需要安装以下软件： - - * [Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) - - * 1.9或更高版本的 [Golang](https://golang.org/doc/install) - - * [make](https://www.gnu.org/software/make/) - - * [gcc compiler/linker](https://gcc.gnu.org/) - - - -* 在环境变量中设置 `$GOPATH`。 - - - -* 你需要知道如何在一个 GitHub 项目仓库中创建一个 PR。一般来说，这涉及到创建仓库的一个分支。想了解更多信息，请参见[创建一个文档 PR](/docs/home/contribute/create-pull-request/)。 - - +阅读参考文档快速入门指南中的[准备工作](/docs/contribute/generate-ref-docs/quickstart/#before-you-begin)节。 - -## 下载两个仓库 - - - -如果你还没有下载过 `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/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`。下文将该目录称为 ``。 - -{{< note >}} - - -如果你只想生成参考文档，而不需要修改，则不需要手动下载 `kubernetes/kubernetes` 仓库。当你运行 `update-imported-docs` 工具时，它会自动克隆 `kubernetes/kubernetes` 仓库。 -{{< /note >}} - - - -## 编辑 Kubernetes 源码 - - - -Kubernetes 组件和工具的参考文档是基于 Kubernetes 源码自动生成的。如果想要修改参考文档，可以从修改 Kubernetes 源码中的一个或多个注释开始。在本地 kubernetes/kubernetes 仓库中进行修改，然后向 [github.com/kubernetes/kubernetes](https://github.com/kubernetes/kubernetes) 的 master 分支提交 PR。 - - - -[PR 56942](https://github.com/kubernetes/kubernetes/pull/56942) 是一个对 Kubernetes 源码中的注释进行修改的 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 >}} - - - -## update-imported-docs 概述 - - - -`update-imported-docs` 工具在 `kubernetes/website/update-imported-docs/` 目录下。它执行以下步骤： - - - -1. 克隆配置文件中指定的相关仓库。为了生成参考文档，默认情况下克隆的仓库是 `kubernetes-incubator/reference-docs` 和 `kubernetes/federation`。 -1. 在克隆出的仓库下运行命令来准备文档生成器，然后生成 Markdown 文件。 -1. 将生成的 Markdown 文件复制到配置文件中指定的 `kubernetes/website` 仓库的本地目录中。 - - - -当 Markdown 文件放入 `kubernetes/website` 仓库的本地目录中后，你就可以创建 [PR](/docs/home/contribute/create-pull-request/) 将它们提交到 `kubernetes/website`。 - - - -## 自定义 reference.yml 配置文件 - - - -打开 `/update-imported-docs/reference.yml` 进行编辑。不要修改 `generate-command` 条目的内容，除非你了解它的作用，并且需要修改指定的已发布分支。 - -```yaml -repos: -- name: reference-docs - remote: https://github.com/kubernetes-sigs/reference-docs.git - # This and the generate-command below needs a change when reference-docs has - # branches properly defined - branch: master - generate-command: | - cd $GOPATH - git clone https://github.com/kubernetes/kubernetes.git src/k8s.io/kubernetes - cd src/k8s.io/kubernetes - git checkout release-1.17 - make generated_files - cp -L -R vendor $GOPATH/src - rm -r vendor - cd $GOPATH - go get -v github.com/kubernetes-sigs/reference-docs/gen-compdocs - cd src/github.com/kubernetes-sigs/reference-docs/ - make comp -``` - - - -在 reference.yml 中，`files` 字段是 `src` 和 `dst` 字段的列表。`src` 字段指定生成的 Markdown 文件的位置，而 `dst` 字段指定将此文件复制到 `kubernetes/website` 仓库的本地目录的哪个位置。例如： - -```yaml -repos: -- name: reference-docs - remote: https://github.com/kubernetes-incubator/reference-docs.git - files: - - src: gen-compdocs/build/kube-apiserver.md - dst: content/en/docs/reference/command-line-tools-reference/kube-apiserver.md - ... -``` - - - -注意，当有许多文件要从同一个源目录复制到同一个目标目录时，可以使用通配符给 `src` 赋值，而使用目录名给 `dst` 赋值。例如： - -```shell - files: - - src: gen-compdocs/build/kubeadm*.md - dst: content/en/docs/reference/setup-tools/kubeadm/generated/ -``` - - - -## 运行 update-imported-docs 工具 - - - -在检查与或自定义 `reference.yaml` 文件后，运行 `update-imported-docs` 工具： - -```shell -cd /update-imported-docs -./update-imported-docs reference.yml -``` - - - -## 在 kubernetes/website 中添加和提交修改 - - - -列出生成并准备合入到 `kubernetes/website` 仓库中的文件： - -``` -cd -git status -``` - - - -输出展示了新增和修改的文件。例如，输出可能如下所示： - -```shell -... - - modified: content/en/docs/reference/command-line-tools-reference/cloud-controller-manager.md - modified: content/en/docs/reference/command-line-tools-reference/federation-apiserver.md - modified: content/en/docs/reference/command-line-tools-reference/federation-controller-manager.md - modified: content/en/docs/reference/command-line-tools-reference/kube-apiserver.md - modified: content/en/docs/reference/command-line-tools-reference/kube-controller-manager.md - modified: content/en/docs/reference/command-line-tools-reference/kube-proxy.md - modified: content/en/docs/reference/command-line-tools-reference/kube-scheduler.md -... -``` - - - -运行 `git add` 和 `git commit` 将提交上述文件。 - - - -## 创建 PR - - - -对 `kubernetes/website` 仓库创建 PR。跟踪你的 PR，并根据需要回应评审人的评论。继续跟踪你的 PR，直到它被合入。 - - - -在 PR 合入的几分钟后，你更新的参考主题将出现在[已发布文档](/docs/home/)中。 - - +按照[参考文档快速入门](/docs/contribute/generate-ref-docs/quickstart/) +指引，生成 Kubernetes 组件和工具的参考文档。 ## {{% heading "whatsnext" %}} - -* [为 kubectl 命令集生成参考文档](/docs/home/contribute/generated-reference/kubectl/) -* [为 Kubernetes API 生成参考文档](/docs/home/contribute/generated-reference/kubernetes-api/) -* [为 Kubernetes 联邦 API 生成参考文档](/docs/home/contribute/generated-reference/federation-api/) +* [生成参考文档快速入门](/docs/home/contribute/generate-ref-docs/quickstart/) +* [为 kubectll 命令生成参考文档](/docs/home/contribute/generate-ref-docs/kubectl/) +* [为 Kubernetes API 生成参考文档](/docs/home/contribute/generate-ref-docs/kubernetes-api/) +* [为上游 Kubernetes 项目做贡献以改进文档](/docs/contribute/generate-ref-docs/contribute-upstream/) diff --git a/content/zh/docs/contribute/generate-ref-docs/prerequisites-ref-docs.md b/content/zh/docs/contribute/generate-ref-docs/prerequisites-ref-docs.md new file mode 100644 index 0000000000..4a52bfa997 --- /dev/null +++ b/content/zh/docs/contribute/generate-ref-docs/prerequisites-ref-docs.md @@ -0,0 +1,45 @@ + + +### 需求 {#requirements} + +- 你需要一台 Linux 或 macOS 机器。 + +- 你需要安装以下工具： + + - [Python](https://www.python.org/downloads/) v3.7.x + - [Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) + - [Golang](https://golang.org/doc/install) 1.13+ 版本 + - 用来安装 PyYAML 的 [Pip](https://pypi.org/project/pip/) + - [PyYAML](https://pyyaml.org/) v5.1.2 + - [make](https://www.gnu.org/software/make/) + - [gcc compiler/linker](https://gcc.gnu.org/) + - [Docker](https://docs.docker.com/engine/installation/) （仅用于 `kubectl` 命令参考） + + +- 你的 `PATH` 环境变量必须包含所需要的构建工具，例如 `Go` 程序和 `python`。 + +- 你需要知道如何为一个 GitHub 仓库创建拉取请求（PR）。 + 这牵涉到创建仓库的派生（fork）副本。 + 有关信息可进一步查看[基于本地副本开展工作](/docs/contribute/intermediate/#work_from_a_local_clone)。 + diff --git a/content/zh/docs/contribute/generate-ref-docs/quickstart.md b/content/zh/docs/contribute/generate-ref-docs/quickstart.md new file mode 100644 index 0000000000..4011b5f9b8 --- /dev/null +++ b/content/zh/docs/contribute/generate-ref-docs/quickstart.md @@ -0,0 +1,405 @@ +--- +title: 快速入门 +content_type: task +weight: 40 +--- + + + + + +本页讨论如何使用 `update-imported-docs` 脚本来生成 Kubernetes 参考文档。 +此脚本将构建的配置过程自动化，并为某个发行版本生成参考文档。 + +## {{% heading "prerequisites" %}} + +{{< include "prerequisites-ref-docs.md" >}} + + + +## 获取文档仓库 {#getting-the-docs-repository} + +确保你的 `website` 派生仓库与 `kubernetes/website` 主分支一致，并克隆 +你的派生仓库。 + +```shell +mkdir github.com +cd github.com +git clone git@github.com:/website.git +``` + + +确定你的克隆副本的根目录。例如，如果你按照前面的步骤获取了仓库，你的根目录 +会是 `github.com/website`。接下来的步骤中，`` 用来指代你的根目录。 + +{{< note>}} +如果你希望更改构建工具和 API 参考资料，可以阅读 +[上游贡献指南](/docs/contribute/generate-ref-docs/contribute-upstream). +{{< /note >}} + + +## update-imported-docs 的概述 + +脚本 `update-imported-docs` 位于 `/update-imported-docs/` 目录下， +能够生成以下参考文档： + +* Kubernetes 组件和工具的参考页面 +* `kubectl` 命令参考文档 +* Kubernetes API 参考文档 + + +脚本 `update-imported-docs` 基于 Kubernetes 源代码生成参考文档。 +过程中会在你的机器的 `/tmp` 目录下创建临时目录，克隆所需要的仓库 +`kubernetes/kubernetes` 和 `kubernetes-sigs/reference-docs` 到此临时目录。 +脚本会将 `GOPATH` 环境变量设置为指向此临时目录。 +此外，脚本会设置三个环境变量： + +* `K8S_RELEASE` +* `K8S_ROOT` +* `K8S_WEBROOT` + + +脚本需要两个参数才能成功运行： + +* 一个 YAML 配置文件（`reference.yml`） +* 一个发行版本字符串，例如：`1.17` + +配置文件中包含 `generate-command` 字段，其中定义了一系列来自于 +`kubernetes-sigs/reference-docs/Makefile` 的构建指令。 +变量 `K8S_RELEASE` 用来确定所针对的发行版本。 + + +脚本 `update-imported-docs` 执行以下步骤： + +1. 克隆配置文件中所指定的相关仓库。就生成参考文档这一目的而言，要克隆的 + 仓库默认为 `kubernetes-sigs/reference-docs`。 +1. 在所克隆的仓库下运行命令，准备文档生成器，之后生成 HTML 和 Markdown 文件。 +1. 将所生成的 HTML 和 Markdown 文件复制到 `` 本地克隆副本中， + 放在配置文件中所指定的目录下。 +1. 更新 `kubectl.md` 文件中对 `kubectl` 命令文档的链接，使之指向 `kubectl` + 命令参考中对应的节区。 + + +当所生成的文件已经被放到 `` 目录下，你就可以将其提交到你的派生副本中， +并基于所作提交发起[拉取请求（PR）](/docs/contribute/start/)到 k/website 仓库。 + + +## 配置文件格式 {#configuration-file-format} + +每个配置文件可以包含多个被导入的仓库。当必要时，你可以通过手工编辑此文件进行定制。 +你也可以通过创建新的配置文件来导入其他文档集合。 +下面是 YAML 配置文件的一个例子： + +```yaml +repos: +- name: community + remote: https://github.com/kubernetes/community.git + branch: master + files: + - src: contributors/devel/README.md + dst: docs/imported/community/devel.md + - src: contributors/guide/README.md + dst: docs/imported/community/guide.md +``` + + +通过工具导入的单页面的 Markdown 文档必须遵从 +[文档样式指南](/docs/contribute/style/style-guide/)。 + + + +## 定制 reference.yml + +打开 `/update-imported-docs/reference.yml` 文件进行编辑。 +在不了解参考文档构造命令的情况下，不要更改 `generate-command` 字段的内容。 +你一般不需要更新 `reference.yml` 文件。不过也有时候上游的源代码发生变化， +导致需要对配置文件进行更改（例如：Golang 版本依赖或者第三方库发生变化）。 +如果你遇到类似问题，请在 [Kubernetes Slack 的 #sig-docs 频道](https://kubernetes.slack.com) +联系 SIG-Docs 团队。 + + + +{{< note >}} +注意，`generate-command` 是一个可选项，用来运行指定命令或者短脚本以在仓库 +内生成文档。 +{{< /note >}} + +在 `reference.yml` 文件中，`files` 属性包含了一组 `src` 和 `dst` 字段。 +`src` 字段给出在所克隆的 `kubernetes-sigs/reference-docs` 构造目录中生成的 +Markdown 文件的位置，而 `dst` 字段则给出了对应文件要复制到的、所克隆的 +`kubernetes/website` 仓库中的位置。例如： + +```yaml +repos: +- name: reference-docs + remote: https://github.com/kubernetes-sigs/reference-docs.git + files: + - src: gen-compdocs/build/kube-apiserver.md + dst: content/en/docs/reference/command-line-tools-reference/kube-apiserver.md + ... +``` + + +注意，如果从同一源目录中有很多文件要复制到目标目录，你可以在为 `src` 所设置的 +值中使用通配符。这时，为 `dst` 所设置的值必须是目录名称。例如： + +```yaml + files: + - src: gen-compdocs/build/kubeadm*.md + dst: content/en/docs/reference/setup-tools/kubeadm/generated/ +``` + + +## 运行 update-imported-docs 工具 + +你可以用如下方式运行 `update-imported-docs` 工具： + +```shell +cd /update-imported-docs +./update-imported-docs +``` + + +例如： + +```shell +./update-imported-docs reference.yml 1.17 +``` + + + +## 修复链接 + +配置文件 `release.yml` 中包含用来修复相对链接的指令。 +若要修复导入文件中的相对链接，将 `gen-absolute-links` 属性设置为 `true`。 +你可以在 [`release.yml`](https://github.com/kubernetes/website/blob/master/update-imported-docs/release.yml) +文件中找到示例。 + + +## 添加并提交 kubernetes/website 中的变更 + +枚举新生成并复制到 `` 的文件： + +```shell +cd +git status +``` + + +输出显示新生成和已修改的文件。取决于上游源代码的修改多少， +所生成的输出也会不同。 + +### 生成的 Kubernetes 组件文档 + +``` +content/en/docs/reference/command-line-tools-reference/cloud-controller-manager.md +content/en/docs/reference/command-line-tools-reference/kube-apiserver.md +content/en/docs/reference/command-line-tools-reference/kube-controller-manager.md +content/en/docs/reference/command-line-tools-reference/kube-proxy.md +content/en/docs/reference/command-line-tools-reference/kube-scheduler.md +content/en/docs/reference/setup-tools/kubeadm/generated/kubeadm.md +content/en/docs/reference/kubectl/kubectl.md +``` + + +### 生成的 kubectl 命令参考文件 + +``` +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/css/font-awesome.min.css +``` + + +### 生成的 Kubernetes API 参考目录与文件 + +``` +static/docs/reference/generated/kubernetes-api/{{< param "version" >}}/index.html +static/docs/reference/generated/kubernetes-api/{{< param "version" >}}/js/navData.js +static/docs/reference/generated/kubernetes-api/{{< param "version" >}}/js/scroll.js +static/docs/reference/generated/kubernetes-api/{{< param "version" >}}/js/query.scrollTo.min.js +static/docs/reference/generated/kubernetes-api/{{< param "version" >}}/css/font-awesome.min.css +static/docs/reference/generated/kubernetes-api/{{< param "version" >}}/css/bootstrap.min.css +static/docs/reference/generated/kubernetes-api/{{< param "version" >}}/css/stylesheet.css +static/docs/reference/generated/kubernetes-api/{{< param "version" >}}/fonts/FontAwesome.otf +static/docs/reference/generated/kubernetes-api/{{< param "version" >}}/fonts/fontawesome-webfont.eot +static/docs/reference/generated/kubernetes-api/{{< param "version" >}}/fonts/fontawesome-webfont.svg +static/docs/reference/generated/kubernetes-api/{{< param "version" >}}/fonts/fontawesome-webfont.ttf +static/docs/reference/generated/kubernetes-api/{{< param "version" >}}/fonts/fontawesome-webfont.woff +static/docs/reference/generated/kubernetes-api/{{< param "version" >}}/fonts/fontawesome-webfont.woff2 +``` + + +运行 `git add` 和 `git commit` 提交文件。 + +## 创建拉取请求 {#creating-a-pull-request} + +接下来创建一个对 `kubernetes/website` 仓库的拉取请求（PR）。 +监视所创建的 PR，并根据需要对评阅意见给出反馈。 +继续监视该 PR 直到其被合并为止。 + +当你的 PR 被合并几分钟之后，你所做的对参考文档的变更就会出现 +[发布的文档](/docs/home/)上。 + +## {{% heading "whatsnext" %}} + + +要手动设置所需的构造仓库，执行构建目标，以生成各个参考文档，可参考下面的指南： + +* [为 Kubernetes 组件和工具生成参考文档](/docs/contribute/generate-ref-docs/kubernetes-components/) +* [为 kubeclt 命令生成参考文档](/docs/contribute/generate-ref-docs/kubectl/) +* [为 Kubernetes API 生成参考文档](/docs/contribute/generate-ref-docs/kubernetes-api/) +