kubernetes
/
website
mirror of https://github.com/kubernetes/website.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #22242 from tengqm/sync-zh-contrib-2 

[zh] Sync contribution guidelines (2)
This commit is contained in:
Kubernetes Prow Robot 2020-07-12 02:48:01 -07:00 committed by GitHub
parent 503e15009b e8aa064289
commit 38d8c863c3
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
7 changed files with 845 additions and 872 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

17
content/zh/docs/contribute/generate-ref-docs/_index.md
View File

@ -5,17 +5,22 @@ weight: 80
---
<!--
---
title: Reference docs overview
main_menu: true
weight: 80
---
-->
<!--
Much of the Kubernetes reference documentation is generated from Kubernetes
source code, using scripts. The topics in this section document how to generate
this type of content.
The topics in this section document how to generate the Kubernetes
reference guides.
To build the reference documentation, see the following guide:
* [Generating Reference Documentation Quickstart](/docs/contribute/generate-ref-docs/quickstart/)
-->
许多 Kubernetes 参考文档都是使用脚本从 Kubernetes 源代码生成的。本节的主题是如何生成这种类型的文档。
本节的主题是描述如何生成 Kubernetes 参考指南。
要生成参考文档，请参考下面的指南：
* [生成参考文档快速入门](/docs/contribute/generate-ref-docs/quickstart/)

221
content/zh/docs/contribute/generate-ref-docs/contribute-upstream.md
View File

@ -1,12 +1,12 @@
---
title: 为上游 Kubernetes 代码库做出贡献
content_type: task
weight: 20
---
<!--
---
title: Contributing to the Upstream Kubernetes Code
content_type: task
---
weight: 20
-->
<!-- overview -->
@ -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` 等）
中发现的错误。
<!--
If you instead want to regenerate the reference documentation for the Kubernetes
API or the `kube-*` components from the upstream code, see the following instructions:
-->
相反，如果您想从上游代码重新生成 Kubernetes API 或 `kube-*` 组件的参考文档。请参考以下说明：
<!--
- [Generating Reference Documentation for the Kubernetes API](/docs/contribute/generate-ref-docs/kubernetes-api/)
- [Generating Reference Documentation for the Kubernetes Components and Tools](/docs/contribute/generate-ref-docs/kubernetes-components/)
-->
如果您仅想从上游代码重新生成 Kubernetes API 或 `kube-*` 组件的参考文档。请参考以下说明：
- [生成 Kubernetes API 的参考文档](/docs/contribute/generate-ref-docs/kubernetes-api/)
- [生成 Kubernetes 组件和工具的参考文档](/docs/contribute/generate-ref-docs/kubernetes-components/)
## {{% heading "prerequisites" %}}
<!--
You need to have these tools installed:
- [Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)
- [Golang](https://golang.org/doc/install) version 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) 的 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) version 1.9.1 or later
* [Docker](https://docs.docker.com/engine/installation/)
* [etcd](https://github.com/coreos/etcd/)
- Your $GOPATH environment variable must be set, and the location of `etcd`
must be in your $PATH environment variable.
-->
* [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` 环境变量中。
<!--
Your $GOPATH environment variable must be set, and the location of `etcd`
must be in your $PATH environment variable.
- You need to know how to create a pull request to a GitHub repository.
Typically, this involves creating a fork of the repository.
For more information, see
[Creating a Pull Request](https://help.github.com/articles/creating-a-pull-request/) and
[GitHub Standard Fork & Pull Request Workflow](https://gist.github.com/Chaser324/ce0505fbed06b947d962).
-->
必须设置 $GOPATH 环境变量，并且 `etcd` 的位置必须在 $PATH 环境变量中。
<!--
You need to know how to create a pull request to a GitHub repository.
Typically, this involves creating a fork of the repository. For more
information, see
[Creating a Pull Request](https://help.github.com/articles/creating-a-pull-request/) and
[GitHub Standard Fork & Pull Request Workflow](https://gist.github.com/Chaser324/ce0505fbed06b947d962).
-->
您需要知道如何创建对 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)。
<!-- steps -->
<!--
## The big picture
-->
## 基本原则
<!--
The reference documentation for the Kubernetes API and the `kube-*` components
such as `kube-apiserver`, `kube-controller-manager` are automatically generated
from the source code in the [upstream Kubernetes](https://github.com/kubernetes/kubernetes/).
-->
Kubernetes API 和 `kube-*` 组件（例如 `kube-apiserver`、`kube-controller-manager`）的参考文档是根据[上游 Kubernetes](https://github.com/kubernetes/kubernetes/) 中的源代码自动生成的。
<!--
When you see bugs in the generated documentation, you may want to consider
creating a patch to fix it in the upstream project.
-->
## 基本说明
Kubernetes API 和 `kube-*` 组件（例如 `kube-apiserver`、`kube-controller-manager`）的参考文档
是根据[上游 Kubernetes](https://github.com/kubernetes/kubernetes/) 中的源代码自动生成的。
当您在生成的文档中看到错误时，您可能需要考虑创建一个 PR 用来在上游项目中对其进行修复。
<!--
## Cloning the Kubernetes repository
If you don't already have the kubernetes/kubernetes repository, get it now:
-->
## 克隆 Kubernetes 代码仓库
<!--
If you don't already have the kubernetes/kubernetes repository, get it now:
-->
如果您还没有 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 `<k8s-base>`.
-->
确定您的 [kubernetes/kubernetes](https://github.com/kubernetes/kubernetes) 代码仓库克隆的基本目录。
例如，如果按照前面的步骤获取代码仓库，则您的基本目录为 `$GOPATH/src/github.com/kubernetes/kubernetes`。
接下来其余步骤将您的基本目录称为 `<k8s-base>`。
确定您的 [kubernetes/kubernetes](https://github.com/kubernetes/kubernetes) 代码仓库克隆的根目录。
例如，如果按照前面的步骤获取代码仓库，则你的根目录为 `$GOPATH/src/github.com/kubernetes/kubernetes`。
接下来其余步骤将你的根目录称为 `<k8s-base>`。
<!--
Determine the base directory of your clone of the
[kubernetes-sigs/reference-docs](https://github.com/kubernetes-sigs/reference-docs) repository.
@ -127,22 +118,24 @@ For example, if you followed the preceding step to get the repository, your
base directory is `$GOPATH/src/github.com/kubernetes-sigs/reference-docs.`
The remaining steps refer to your base directory as `<rdocs-base>`.
-->
确定您的 [kubernetes-sigs/reference-docs](https://github.com/kubernetes-sigs/reference-docs) 代码仓库克隆的基本目录。
例如，如果按照前面的步骤获取代码仓库，则您的基本目录为 `$GOPATH/src/github.com/kubernetes-sigs/reference-docs`。
接下来其余步骤将您的基本目录称为 `<rdocs-base>`。
确定您的 [kubernetes-sigs/reference-docs](https://github.com/kubernetes-sigs/reference-docs)
代码仓库克隆的根目录。
例如，如果按照前面的步骤获取代码仓库，则你的根目录为
`$GOPATH/src/github.com/kubernetes-sigs/reference-docs`。
接下来其余步骤将你的根目录称为 `<rdocs-base>`。
<!--
## Editing the Kubernetes source code
-->
## 编辑 Kubernetes 源代码
<!--
The Kubernetes API reference documentation is automatically generated from
an OpenAPI spec, which is generated from the Kubernetes source code. If you
want to change the API reference documentation, the first step is to change one
or more comments in the Kubernetes source code.
-->
Kubernetes API 参考文档是根据 OpenAPI 规范自动生成的，该规范是从 Kubernetes 源代码生成的。如果要更改 API 参考文档，第一步是更改 Kubernetes 源代码中的一个或多个注释。
## 编辑 Kubernetes 源代码
Kubernetes API 参考文档是根据 OpenAPI 规范自动生成的，该规范是从 Kubernetes 源代码生成的。
如果要更改 API 参考文档，第一步是更改 Kubernetes 源代码中的一个或多个注释。
<!--
The documentation for the `kube-*` components is also generated from the upstream
@ -153,27 +146,25 @@ you want to fix in order to fix the generated documentation.
<!--
### Making changes to the upstream source code
-->
### 更改上游 Kubernetes 源代码
<!--
The following steps are an example, not a general procedure. Details
will be different in your situation.
-->
### 更改上游 Kubernetes 源代码
{{< note >}}
以下步骤仅作为示例，不是一般步骤，具体情况因您而异。
以下步骤仅作为示例，不是通用步骤，具体情况因环境而异。
{{< /note >}}
<!--
Here's an example of editing a comment in the Kubernetes source code.
-->
以下在 Kubernetes 源代码中编辑注释的示例。
<!--
In your local kubernetes/kubernetes repository, check out the master branch,
and make sure it is up to date:
-->
在您本地的 kubernetes/kubernetes 代码仓库中，切换出本地 master 分支，并确保它是最新的：
以下在 Kubernetes 源代码中编辑注释的示例。
在您本地的 kubernetes/kubernetes 代码仓库中，检出 master 分支，并确保它是最新的：
```shell
cd <k8s-base>
@ -184,19 +175,18 @@ git pull https://github.com/kubernetes/kubernetes master
<!--
Suppose this source file in the master branch has the typo "atmost":
-->
假设 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)
<!--
In your local environment, open `types.go`, and change "atmost" to "at most".
-->
在您的本地环境中，打开 `types.go` 文件，然后将 "atmost" 更改为 "at most"。
<!--
Verify that you have changed the file:
-->
以下命令查看您已更改的文件：
在你的本地环境中，打开 `types.go` 文件，然后将 "atmost" 更改为 "at most"。
以下命令验证你已经更改了文件：
```shell
git status
@ -216,23 +206,22 @@ On branch master
<!--
### Committing your edited file
-->
### 提交已编辑的文件
<!--
Run `git add` and `git commit` to commit the changes you have made so far. In the next step,
you will do a second commit. It is important to keep your changes separated into two commits.
-->
运行 `git add` 和 `git commit` 命令提交到目前为止所做的更改。在下一步中，您将进行第二次提交，将更改分成两个提交很重要。
### 提交已编辑的文件
运行 `git add` 和 `git commit` 命令提交到目前为止所做的更改。
在下一步中，您将进行第二次提交，将更改分成两个提交很重要。
<!--
### Generating the OpenAPI spec and related files
Go to `<k8s-base>` and run these scripts:
-->
### 生成 OpenAPI 规范和相关文件
<!--
Go to `<k8s-base>` and run these scripts:
-->
进入 `<k8s-base>` 目录并运行以下脚本：
```shell
@ -242,12 +231,10 @@ hack/update-generated-protobuf.sh
hack/update-api-reference-docs.sh
```
<!--
Run `git status` to see what was generated.
-->
运行 `git status` 命令查看生成的东西。
<!-- Run `git status` to see what was generated. -->
运行 `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` 是文档生成过程中第二阶段的输入。
<!--
Run `git add` and `git commit` to commit your changes. Now you have two commits:
one that contains the edited `types.go` file, and one that contains the generated OpenAPI spec
and related files. Keep these two commits separate. That is, do not squash your commits.
-->
运行 `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)
is an example of a pull request that fixes a typo in the Kubernetes source code.
-->
[PR 57758](https://github.com/kubernetes/kubernetes/pull/57758) 是修复 Kubernetes 源代码中的拼写错误的拉取请求的示例。
[PR 57758](https://github.com/kubernetes/kubernetes/pull/57758) 是修复 Kubernetes
源代码中的拼写错误的拉取请求的示例。
<!--
It can be tricky to determine the correct source file to be changed. In the
@ -302,22 +294,30 @@ repository and in related repositories, such as
[kubernetes/apiserver](https://github.com/kubernetes/apiserver/blob/master/README.md).
-->
{{< 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 picking your commit into a release branch
-->
### Cherry Pick 将您的提交纳入发布分支
<!--
In the preceding section, you edited a file in the master branch and then ran scripts
to generate an OpenAPI spec and related files. Then you submitted your changes in a pull request
to the master branch of the kubernetes/kubernetes repository. Now suppose you want to backport
your change into a release branch. For example, suppose the master branch is being used to develop
Kubernetes version 1.10, and you want to backport your change into the release-1.9 branch.
-->
在上一节中，您在 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 分支。
<!--
Recall that your pull request has two commits: one for editing `types.go`
@ -326,7 +326,10 @@ commit into the release-1.9 branch. The idea is to cherry pick the commit that e
the commit that has the results of running the scripts. For instructions, see
[Propose a Cherry Pick](https://git.k8s.io/community/contributors/devel/sig-release/cherry-picks.md).
-->
回想一下，您的 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)。
<!--
Proposing a cherry pick requires that you have permission to set a label and a milestone in your
@ -334,14 +337,16 @@ pull request. If you don't have those permissions, you will need to work with so
and milestone for you.
-->
{{< note >}}
提出 cherry pick 要求您有权在 pull request 中设置标签和里程碑。如果您没有这些权限，则需要与可以为您设置标签和里程碑的人员合作。
提出 Cherry Pick 要求你有权在 PR 中设置标签和里程碑。如果您没有这些权限，
则需要与可以为你设置标签和里程碑的人员合作。
{{< /note >}}
<!--
When you have a pull request in place for cherry picking your one commit into the release-1.9 branch,
the next step is to run these scripts in the release-1.9 branch of your local environment.
-->
当您提出一个 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 分支中为止。
<!--
At this point, both the master branch and the release-1.9 branch have your updated `types.go`
@ -364,36 +370,37 @@ the same as the generated files in the master branch. The generated files in the
contain API elements only from Kubernetes 1.9. The generated files in the master branch might contain
API elements that are not in 1.9, but are under development for 1.10.
-->
此时，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 元素。
<!--
## Generating the published reference docs
-->
## 生成已发布的参考文档
<!--
The preceding section showed how to edit a source file and then generate
several files, including `api/openapi-spec/swagger.json` in the
`kubernetes/kubernetes` repository.
The `swagger.json` file is the OpenAPI definition file to use for generating
the API reference documentation.
-->
上一节显示了如何编辑源文件然后生成多个文件，包括在 `kubernetes/kubernetes` 代码仓库中的 `api/openapi-spec/swagger.json`。
`swagger.json` 文件是 OpenAPI 定义文件，可用于生成 API 参考文档。
## 生成已发布的参考文档
上一节显示了如何编辑源文件然后生成多个文件，包括在 `kubernetes/kubernetes` 代码仓库中的
`api/openapi-spec/swagger.json`。`swagger.json` 文件是 OpenAPI 定义文件，可用于生成 API 参考文档。
<!--
You are now ready to follow the [Generating Reference Documentation for the Kubernetes API](/docs/contribute/generate-ref-docs/kubernetes-api/) guide to generate the
[published Kubernetes API reference documentation](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/).
-->
现在，您可以按照[生成 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" %}}
<!--
* [Generating Reference Documentation for the Kubernetes API](/docs/contribute/generate-ref-docs/kubernetes-api/)
* [Generating Reference Docs for Kubernetes Components and Tools](/docs/home/contribute/generated-reference/kubernetes-components/)
@ -403,5 +410,3 @@ You are now ready to follow the [Generating Reference Documentation for the Kube
* [为 Kubernetes 组件和工具生成参考文档](/docs/home/contribute/generated-reference/kubernetes-components/)
* [生成 kubectl 命令的参考文档](/docs/home/contribute/generated-reference/kubectl/)

319
content/zh/docs/contribute/generate-ref-docs/kubectl.md
View File

@ -1,106 +1,65 @@
---
title: 为 kubectl 命令集生成参考文档
content_type: task
weight: 90
---
<!--
---
title: Generating Reference Documentation for kubectl Commands
content_type: task
---
weight: 90
-->
<!-- overview -->
<!--
This page shows how to automatically generate reference pages for the
commands provided by the `kubectl` tool.
This page shows how to generate the `kubectl` command reference.
-->
该页面显示了如何自动生成 `kubectl` 工具提供的命令的参考页面。
本页面描述了如何生成 `kubectl` 命令参考。
{{< note >}}
<!--
This topic shows how to generate reference documentation for
[kubectl commands](/docs/reference/generated/kubectl/kubectl-commands)
like
[kubectl apply](/docs/reference/generated/kubectl/kubectl-commands#apply) and
[kubectl taint](/docs/reference/generated/kubectl/kubectl-commands#taint).
-->
本主题展示了如何为 [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)。
<!--
This topic does not show how to generate the
[kubectl](/docs/reference/generated/kubectl/kubectl/)
options reference page. For instructions on how to generate the kubectl options
reference page, see
[Generating Reference Pages for Kubernetes Components and Tools](/docs/home/contribute/generated-reference/kubernetes-components/).
-->
本主题没有展示如何生成 [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" %}}
<!--
* You need to have
[Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)
installed.
-->
* 你需要安装 [Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)。
<!--
* You need to have
[Golang](https://golang.org/doc/install) version 1.9.1 or later installed,
and your `$GOPATH` environment variable must be set.
-->
* 你需要安装 1.9.1 或更高版本的 [Golang](https://golang.org/doc/install), 并在环境变量中设置 `$GOPATH`。
<!--
* You need to have
[Docker](https://docs.docker.com/engine/installation/) installed.
-->
* 你需要安装 [Docker](https://docs.docker.com/engine/installation/)。
<!--
* You need to know how to create a pull request to a GitHub repository.
Typically, this involves creating a fork of the repository. For more
information, see
[Creating a Documentation Pull Request](/docs/home/contribute/create-pull-request/) and
[GitHub Standard Fork & Pull Request Workflow](https://gist.github.com/Chaser324/ce0505fbed06b947d962).
-->
* 你需要知道如何在一个 GitHub 项目仓库中创建一个 PR。一般来说，这涉及到创建仓库的一个分支。想了解更多信息，请参见[创建一个文档 PR](/docs/home/contribute/create-pull-request/) 和 [GitHub 标准 Fork & PR 工作流](https://gist.github.com/Chaser324/ce0505fbed06b947d962)。
{{< include "prerequisites-ref-docs.md" >}}
<!-- steps -->
<!--
## Setting up the local repositories
-->
## 设置本地仓库
<!--
Create a local workspace and set your `GOPATH`.
-->
创建本地工作区并设置您的 `GOPATH`。
## 配置本地仓库
创建本地工作区并设置你的 `GOPATH`。
```shell
mkdir -p $HOME/<workspace>
export GOPATH=$HOME/<workspace>
```
<!--
Get a local clone of the following repositories:
-->
<!-- Get a local clone of the following repositories: -->
获取以下仓库的本地克隆：
```shell
@ -113,16 +72,14 @@ go get -u kubernetes-incubator/reference-docs
<!--
If you don't already have the kubernetes/website repository, get it now:
-->
如果您还没有下载过 `kubernetes/website` 仓库，现在下载：
如果您还没有获取过 `kubernetes/website` 仓库，现在获取之：
```shell
git clone https://github.com/<your-username>/website $GOPATH/src/github.com/<your-username>/website
```
<!--
Get a clone of the kubernetes/kubernetes repository as k8s.io/kubernetes:
-->
克隆下载 kubernetes/kubernetes 仓库，并作为 k8s.io/kubernetes：
<!-- Get a clone of the kubernetes/kubernetes repository as 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
<!--
Remove the spf13 package from `$GOPATH/src/k8s.io/kubernetes/vendor/github.com`.
-->
从 `$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
```
<!--
The kubernetes/kubernetes repository provides access to the kubectl and kustomize source code.
-->
<!-- The kubernetes/kubernetes repository provides access to the kubectl and kustomize source code. -->
kubernetes/kubernetes 仓库提供对 kubectl 和 kustomize 源代码的访问。
<!--
* Determine the base directory of your clone of the
[kubernetes/kubernetes](https://github.com/kubernetes/kubernetes) repository.
@ -150,7 +104,9 @@ For example, if you followed the preceding step to get the repository, your
base directory is `$GOPATH/src/k8s.io/kubernetes.`
The remaining steps refer to your base directory as `<k8s-base>`.
-->
确定 [kubernetes/kubernetes](https://github.com/kubernetes/kubernetes) 仓库的本地主目录。例如，如果按照前面的步骤来获取该仓库，则主目录是 `$GOPATH/src/k8s.io/kubernetes.`。下文将该目录称为 `<k8s-base>`。
* 确定 [kubernetes/kubernetes](https://github.com/kubernetes/kubernetes) 仓库的本地主目录。
例如，如果按照前面的步骤来获取该仓库，则主目录是 `$GOPATH/src/k8s.io/kubernetes.`。
下文将该目录称为 `<k8s-base>`。
<!--
* Determine the base directory of your clone of the
@ -159,198 +115,197 @@ For example, if you followed the preceding step to get the repository, your
base directory is `$GOPATH/src/github.com/<your-username>/website.`
The remaining steps refer to your base directory as `<web-base>`.
-->
确定 [kubernetes/website](https://github.com/kubernetes/website) 仓库的本地主目录。例如，如果按照前面的步骤来获取该仓库，则主目录是 `$GOPATH/src/github.com/<your-username>/website`。下文将该目录称为 `<web-base>`。
* 确定 [kubernetes/website](https://github.com/kubernetes/website) 仓库的本地主目录。
例如，如果按照前面的步骤来获取该仓库，则主目录是 `$GOPATH/src/github.com/<your-username>/website`。
下文将该目录称为 `<web-base>`。
<!--
* Determine the base directory of your clone of the
[kubernetes-incubator/reference-docs](https://github.com/kubernetes-incubator/reference-docs) repository.
[kubernetes-sigs/reference-docs](https://github.com/kubernetes-sigs/reference-docs) repository.
For example, if you followed the preceding step to get the repository, your
base directory is `$GOPATH/src/github.com/kubernetes-incubator/reference-docs.`
base directory is `$GOPATH/src/github.com/kubernetes-sigs/reference-docs.`
The remaining steps refer to your base directory as `<rdocs-base>`. -->
确定 [kubernetes-incubator/reference-docs](https://github.com/kubernetes-incubator/reference-docs) 仓库的本地主目录。例如，如果按照前面的步骤来获取该仓库，则主目录是 `$GOPATH/src/github.com/kubernetes-incubator/reference-docs`。下文将该目录称为 `<rdocs-base>`。
* 确定 [kubernetes-sigs/reference-docs](https://github.com/kubernetes-sigs/reference-docs)
仓库的本地主目录。例如，如果按照前面的步骤来获取该仓库，则主目录是
`$GOPATH/src/github.com/kubernetes-sigs/reference-docs`。
下文将该目录称为 `<rdocs-base>`。
<!--
In your local k8s.io/kubernetes repository, check out the branch of interest,
and make sure it is up to date. For example, if you want to generate docs for
Kubernetes 1.15, you could use these commands:
Kubernetes 1.17, you could use these commands:
-->
在您当地的 k8s.io/kubernetes 仓库中，检查感兴趣的分支并确保它是最新的。例如，如果您想要生成 Kubernetes 1.15 的文档，您可以使用以下命令：
在本地的 k8s.io/kubernetes 仓库中，检出感兴趣的分支并确保它是最新的。例如，
如果你想要生成 Kubernetes 1.17 的文档，可以使用以下命令：
```shell
cd <k8s-base>
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
```
<!--
If you do not need to edit the kubectl source code, follow the instructions to [Edit the Makefile](#editing-makefile).
If you do not need to edit the kubectl source code, follow the instructions to
[Setting build variables](#setting-build-variables).
-->
如果不需要编辑 kubectl 源码，请按照说明[编辑 Makefile](#editing-makefile)。
如果不需要编辑 `kubectl`
源码，请按照说明[配置构建变量](#setting-build-variables)。
<!--
## Editing the kubectl source code
-->
## 编辑 kubectl 源码
<!--
The kubectl command reference documentation is automatically generated from
the kubectl source code. If you want to change the reference documentation, the first step
is to change one or more comments in the kubectl source code. Make the change in your
local kubernetes/kubernetes repository, and then submit a pull request to the master branch of
[github.com/kubernetes/kubernetes](https://github.com/kubernetes/kubernetes).
-->
## 编辑 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)
is an example of a pull request that fixes a typo in the kubectl source code.
-->
[PR 56673](https://github.com/kubernetes/kubernetes/pull/56673/files) 是一个对 kubectl 源码中的笔误进行修复的 PR 示例。
<!--
Monitor your pull request, and respond to reviewer comments. Continue to monitor your
pull request until it is merged into the master branch of the kubernetes/kubernetes repository.
-->
跟踪你的 PR，并回应评审人的评论。继续跟踪你的 PR，直到它合入到 kubernetes/kubernetes 仓库的 master 分支中。
[PR 56673](https://github.com/kubernetes/kubernetes/pull/56673/files) 是一个对 kubectl
源码中的笔误进行修复的 PR 示例。
跟踪你的 PR，并回应评审人的评论。继续跟踪你的 PR，直到它合入到 kubernetes/kubernetes 仓库的
master 分支中。
<!--
## Cherry picking your change into a release branch
-->
## 以 cherry-pick 方式将你的修改合入已发布分支
<!--
Your change is now in the master branch, which is used for development of the next
Kubernetes release. If you want your change to appear in the docs for a Kubernetes
version that has already been released, you need to propose that your change be
cherry picked into the release branch.
-->
## 以 cherry-pick 方式将你的修改合入已发布分支
你的修改已合入 master 分支中，该分支用于开发下一个 Kubernetes 版本。如果你希望修改部分出现在已发布的 Kubernetes 版本文档中，则需要提议将它们以 cherry-pick 方式合入已发布分支。
你的修改已合入 master 分支中，该分支用于开发下一个 Kubernetes 版本。
如果你希望修改部分出现在已发布的 Kubernetes 版本文档中，则需要提议将它们以
cherry-pick 方式合入已发布分支。
<!--
For example, suppose the master branch is being used to develop Kubernetes 1.10,
and you want to backport your change to the release-1.15 branch. For instructions
on how to do this, see
[Propose a Cherry Pick](https://git.k8s.io/community/contributors/devel/sig-release/cherry-picks.md).
-->
例如，假设 master 分支正用于开发 Kubernetes 1.10 版本，而你希望将修改合入到已发布的 1.15 版本分支。相关的操作指南，请参见 [提议一个 cherry-pick 合入](https://git.k8s.io/community/contributors/devel/sig-release/cherry-picks.md)。
<!--
Monitor your cherry-pick pull request until it is merged into the release branch.
-->
例如，假设 master 分支正用于开发 Kubernetes 1.16 版本，而你希望将修改合入到已发布的 1.15 版本分支。
相关的操作指南，请参见
[提议一个 cherry-pick](https://git.k8s.io/community/contributors/devel/sig-release/cherry-picks.md)。
跟踪你的 cherry-pick PR，直到它合入到已发布分支中。
{{< note >}}
<!--
Proposing a cherry pick requires that you have permission to set a label and a
milestone in your pull request. If you don’t have those permissions, you will
need to work with someone who can set the label and milestone for you.
-->
提议一个 cherry-pick 合入，需要你有在 PR 中设置标签和里程碑的权限。如果你没有，你需要与有权限为你设置标签和里程碑的人合作完成。
{{< note >}}
提议一个 cherry-pick 需要你有在 PR 中设置标签和里程碑的权限。
如果你没有，你需要与有权限为你设置标签和里程碑的人合作完成。
{{< /note >}}
<!--
## Editing Makefile
-->
## Setting build variables
## 编辑 Makefile
<!--
Go to `<rdocs-base>`, and open the `Makefile` for editing:
-->
## 设置构建变量 {#setting-build-variables}
进入 `<rdocs-base>` 目录, 打开 `Makefile` 进行编辑：
<!--
* Set `K8SROOT` to `<k8s-base>`.
* Set `WEBROOT` to `<web-base>`.
* Set `MINOR_VERSION` to the minor version of the docs you want to build. For example,
if you want to build docs for Kubernetes 1.15, set `MINOR_VERSION` to 15. Save and close the `Makefile`.
-->
* 设置 `K8SROOT` 为 `<k8s-base>`。
* 设置 `WEBROOT` 为 `<web-base>`。
* 设置 `MINOR_VERSION` 为要构建的文档的次要版本。例如，如果您想为 Kubernetes 1.15 构建文档，请将 `MINOR_VERSION` 设置为 15。保存并关闭 `Makefile` 文件。
* Set `K8S_ROOT` to `<k8s-base>`.
* Set `K8S_WEBROOT` to `<web-base>`.
* 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.
<!--
For example, update the following variables:
-->
例如，更新以下变量：
* 设置 `K8S_ROOT` 为 `<k8s-base>`。
* 设置 `K8S_WEBROOT` 为 `<web-base>`。
* 设置 `K8S_RELEASE` 为要构建文档的版本。
例如，如果您想为 Kubernetes 1.17 构建文档，请将 `K8S_RELEASE` 设置为 1.17。
例如：
```
WEBROOT=$(GOPATH)/src/github.com/<your-username>/website
K8SROOT=$(GOPATH)/src/k8s.io/kubernetes
MINOR_VERSION=15
export K8S_WEBROOT=$(GOPATH)/src/github.com/<your-username>/website
export K8S_ROOT=$(GOPATH)/src/k8s.io/kubernetes
export K8S_RELEASE=1.17
```
<!--
## Creating a version directory
## Creating a versioned directory
The `createversiondirs` build target creates a versioned directory
and copies the kubectl reference configuration files to the versioned directory.
The versioned directory name follows the pattern of `v<major>_<minor>`.
In the `<rdocs-base>` directory, run the following build target:
```shell
cd <rdocs-base>
make createversiondirs
```
-->
## 创建版本目录
<!--
The version directory is a staging area for the kubectl command reference build.
The YAML files in this directory are used to create the structure and navigation
of the kubectl command reference.
-->
版本目录是 kubectl 命令集构建的临时区域。该目录中的 YAML 文件用于创建 kubectl 命令集参考的结构和导航。
构建目标 `createversiondirs` 会生成一个版本目录并将 kubectl 参考配置文件复制到该目录中。
版本目录的名字模式为 `v<major>_<minor>`。
<!--
In the `<rdocs-base>/gen-kubectldocs/generators` directory, if you do not already
have a directory named `v1_<MINOR_VERSION>`, create one now by copying the directory
for the previous version. For example, suppose you want to generate docs for
Kubernetes 1.15, but you don't already have a `v1_15` directory. Then you could
create and populate a `v1_15` directory by running these commands:
-->
在 `gen-kubectldocs/generators` 目录中，如果你还没有一个名为 `v1_MINOR_VERSION` 的目录，那么现在通过复制前一版本的目录来创建一个。例如，假设你想要为 Kubernetes 1.15 版本生成文档，但是还没有 `v1_15` 目录，这时可以通过运行以下命令来创建并填充 `v1_15` 目录：
在 `<rdocs-base>` 目录下，执行下面的命令：
```shell
cd <k8s-base>
git checkout release-1.15
git pull https://github.com/kubernetes/kubernetes release-1.15
cd <rdocs-base>
make createversiondirs
```
<!--
## Checking out a branch in k8s.io/kubernetes
-->
## 从 kubernetes/kubernetes 检出一个分支
<!--
In your local <k8s-base> repository, checkout the branch that has
the version of Kubernetes that you want to document. For example, if you want
to generate docs for Kubernetes 1.15, checkout the release-1.15 branch. Make sure
you local branch is up to date.
-->
## 从 kubernetes/kubernetes 检出一个分支
在本地 <k8s-base> 仓库中，检出你想要生成文档的、包含 Kubernetes 版本的分支。例如，如果希望为 Kubernetes 1.15 版本生成文档，请检出 1.15 分支。确保本地分支是最新的。
在本地 `<k8s-base>` 仓库中，检出你想要生成文档的、包含 Kubernetes 版本的分支。
例如，如果希望为 Kubernetes 1.17 版本生成文档，请检出 `v1.17.0` 标记。
确保本地分支是最新的。
```shell
cd <k8s-base>
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
```
<!--
## Running the doc generation code
-->
## 运行文档生成代码
<!--
In your local kubernetes-incubator/reference-docs repository, build and run the
kubectl command reference generation code. You might need to run the command as root:
-->
## 运行文档生成代码
在 kubernetes-incubator/reference-docs 仓库的本地目录中，构建并运行 kubectl 命令集参数生成代码。你可能需要以 root 用户运行命令：
在本地的 `<rdocs-base>` 目录下，运行 `copycli` 构建目标。此命令以 `root` 账号运行：
```shell
cd <rdocs-base>
@ -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 `<web-base>`.
-->
`copycli` 命令将清理暂存目录，生成 kubectl 命令集文件，并将整理后的 kubectl 参考 HTML 页面和文件复制到 `<web-base>`。
`copycli` 命令将清理暂存目录，生成 kubectl 命令文件，并将整理后的 kubectl 参考 HTML 页面和
文件复制到 `<web-base>`。
<!--
## Locate the generated files
Verify that these two files have been generated:
-->
## 找到生成的文件
<!--
Verify that these two files have been generated:
-->
验证是否已生成以下两个文件：
```shell
@ -380,22 +335,19 @@ Verify that these two files have been generated:
<!--
## Locate the copied files
Verify that all generated files have been copied to your `<web-base>`:
-->
## 找到复制的文件
<!--
Verify that all generated files have been copied to your `<web-base>`:
-->
确认所有生成的文件都已复制到您的 `<web-base>`：
确认所有生成的文件都已复制到你的 `<web-base>`：
```shell
cd <web-base>
git status
```
<!--
The output should include the modified files:
-->
<!-- The output should include the modified files: -->
输出应包括修改后的文件：
```
@ -403,10 +355,9 @@ static/docs/reference/generated/kubectl/kubectl-commands.html
static/docs/reference/generated/kubectl/navData.js
```
<!--
Additionally, the output might show the modified files:
-->
此外，输出可能显示修改后的文件：
<!-- Additionally, the output might show the modified files: -->
此外，输出可能还包含：
```
static/docs/reference/generated/kubectl/scroll.js
@ -421,12 +372,11 @@ static/docs/reference/generated/kubectl/node_modules/font-awesome/css/font-aweso
<!--
## Locally test the documentation
Build the Kubernetes documentation in your local `<web-base>`.
-->
## 在本地测试文档
<!--
Build the Kubernetes documentation in your local `<web-base>`.
-->
在本地 `<web-base>` 中构建 Kubernetes 文档。
```shell
@ -434,55 +384,44 @@ cd <web-base>
make docker-serve
```
<!--
View the [local preview](https://localhost:1313/docs/reference/generated/kubectl/kubectl-commands/).
-->
<!-- View the [local preview](https://localhost:1313/docs/reference/generated/kubectl/kubectl-commands/). -->
查看[本地预览](https://localhost:1313/docs/reference/generated/kubectl/kubectl-commands/)。
<!--
## Adding and committing changes in kubernetes/website
Run `git add` and `git commit` to commit the files.
-->
## 在 kubernetes/website 中添加和提交更改
<!--
Run `git add` and `git commit` to commit the files.
-->
运行 `git add` 和 `git commit` 提交修改文件。
<!--
## Creating a pull request
-->
## 创建 PR
<!--
Create a pull request to the `kubernetes/website` repository. Monitor your
pull request, and respond to review comments as needed. Continue to monitor
your pull request until it is merged.
-->
对 `kubernetes/website` 仓库创建 PR。跟踪你的 PR，并根据需要回应评审人的评论。继续跟踪你的 PR，直到它被合入。
<!--
A few minutes after your pull request is merged, your updated reference
topics will be visible in the
[published documentation](/docs/home).
-->
## 创建 PR
对 `kubernetes/website` 仓库创建 PR。跟踪你的 PR，并根据需要回应评审人的评论。
继续跟踪你的 PR，直到它被合入。
在 PR 合入的几分钟后，你更新的参考主题将出现在[已发布文档](/docs/home/)中。
## {{% heading "whatsnext" %}}
<!--
* [Generating Reference Documentation for Kubernetes Components and Tools](/docs/home/contribute/generated-reference/kubernetes-components/)
* [Generating Reference Documentation for the Kubernetes API](/docs/home/contribute/generated-reference/kubernetes-api/)
* [Generating Reference Documentation for the Kubernetes Federation API](/docs/home/contribute/generated-reference/federation-api/)
* [Generating Reference Documentation Quickstart](/docs/contribute/generate-ref-docs/quickstart/)
* [Generating Reference Documentation for Kubernetes Components and Tools](/docs/contribute/generate-ref-docs/kubernetes-components/)
* [Generating Reference Documentation for the Kubernetes API](/docs/contribute/generate-ref-docs/kubernetes-api/)
-->
* [为 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/)

307
content/zh/docs/contribute/generate-ref-docs/kubernetes-api.md
View File

@ -1,21 +1,22 @@
---
title: 为 Kubernetes API 生成参考文档
content_type: task
weight: 50
---
<!--
---
title: Generating Reference Documentation for the Kubernetes API
content_type: task
---
weight: 50
-->
<!-- overview -->
<!--
This page shows how to update the generated reference docs for the Kubernetes API.
The Kubernetes API reference documentation is built from the
[Kubernetes OpenAPI spec](https://github.com/kubernetes/kubernetes/blob/master/api/openapi-spec/swagger.json)
and tools from [kubernetes-incubator/reference-docs](https://github.com/kubernetes-incubator/reference-docs).
and tools from [kubernetes-sigs/reference-docs](https://github.com/kubernetes-sigs/reference-docs).
If you find bugs in the generated documentation, you need to
[fix them upstream](/docs/contribute/generate-ref-docs/contribute-upstream/).
@ -24,86 +25,54 @@ If you need only to regenerate the reference documentation from the [OpenAPI](ht
spec, continue reading this page.
-->
本页面展示了如何为 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" %}}
<!--
You need to have these tools installed:
-->
你需要安装以下软件：
<!--
* [Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)
* [Golang](https://golang.org/doc/install) version 1.9.1 or later
-->
* [Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)
* 1.9.1 或更高版本的 [Golang](https://golang.org/doc/install)
<!--
You need to know how to create a pull request (PR) to a GitHub repository.
Typically, this involves creating a fork of the repository. For more
information, see
[Creating a Documentation Pull Request](/docs/contribute/start/) and
[GitHub Standard Fork & Pull Request Workflow](https://gist.github.com/Chaser324/ce0505fbed06b947d962).
-->
你需要知道如何在一个 GitHub 项目仓库中创建一个 PR。一般来说，这涉及到创建仓库的 fork 分支。想了解更多信息，请参见[创建一个文档 PR](/docs/contribute/start/) 和 [GitHub 标准 Fork & PR 工作流](https://gist.github.com/Chaser324/ce0505fbed06b947d962)。
{{< include "prerequisites-ref-docs.md" >}}
<!-- steps -->
<!--
## Setting up the local repositories
-->
## 设置本地仓库
<!--
Create a local workspace and set your `GOPATH`.
-->
创建本地工作区并设置您的 `GOPATH`。
## 配置本地仓库
创建本地工作区并设置你的 `GOPATH`。
```shell
mkdir -p $HOME/<workspace>
export GOPATH=$HOME/<workspace>
```
<!--
Get a local clone of the following repositories:
-->
<!-- Get a local clone of the following repositories: -->
获取以下仓库的本地克隆：
```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
```
<!--
If you don't already have the kubernetes/website repository, get it now: -->
如果您还没有下载过 `kubernetes/website` 仓库，现在下载：
<!-- If you don't already have the kubernetes/website repository, get it now: -->
如果你还没有下载过 `kubernetes/website` 仓库，现在下载：
```shell
git clone https://github.com/<your-username>/website $GOPATH/src/github.com/<your-username>/website
```
<!--
Get a clone of the kubernetes/kubernetes repository as k8s.io/kubernetes:
-->
克隆下载 kubernetes/kubernetes 仓库，并作为 k8s.io/kubernetes：
<!-- Get a clone of the kubernetes/kubernetes repository as 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 `<web-base>`.
repository is `$GOPATH/src/github.com/kubernetes-incubator/reference-docs.`
The remaining steps refer to your base directory as `<rdocs-base>`.
-->
* [kubernetes/kubernetes](https://github.com/kubernetes/kubernetes) 仓库克隆后的基本目录为 `$GOPATH/src/k8s.io/kubernetes`。
其余后续步骤将您的基本目录称为 `<k8s-base>`。
* [kubernetes/website](https://github.com/kubernetes/website) 仓库克隆后的基本目录为 `$GOPATH/src/github.com/<your username>/website`。
其余后续步骤将您的基本目录称为 `<web-base>`。
* [kubernetes-incubator/reference-docs](https://github.com/kubernetes-incubator/reference-docs) 仓库克隆后的基本目录为 `$GOPATH/src/github.com/kubernetes-incubator/reference-docs`。
其余后续步骤将您的基本目录称为 `<rdocs-base>`。
* [kubernetes/kubernetes](https://github.com/kubernetes/kubernetes) 仓库克隆后的根目录为
`$GOPATH/src/k8s.io/kubernetes`。 后续步骤将此目录称为 `<k8s-base>`。
* [kubernetes/website](https://github.com/kubernetes/website) 仓库克隆后的根目录为
`$GOPATH/src/github.com/<your username>/website`。后续步骤将此目录称为 `<web-base>`。
* [kubernetes-sigs/reference-docs](https://github.com/kubernetes-sigs/reference-docs)
仓库克隆后的基本目录为 `$GOPATH/src/github.com/kubernetes-sigs/reference-docs`。
后续步骤将此目录称为 `<rdocs-base>`。
<!--
## Generating the API reference docs
-->
## 生成 API 参考文档
<!--
This section shows how to generate the
[published Kubernetes API reference documentation](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/).
-->
## 生成 API 参考文档
本节说明如何生成[已发布的 Kubernetes API 参考文档](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/)。
<!--
### Modifying the Makefile
-->
### 修改 Makefile 文件
### Setting build variables
<!--
Go to `<rdocs-base>`, and open the `Makefile` for editing:
-->
进入 `<rdocs-base>` 目录，然后编辑 `Makefile` 文件：
### 设置构建变量 {#setting-build-variables}
<!--
* Set `K8SROOT` to `<k8s-base>`.
* Set `WEBROOT` to `<web-base>`.
* Set `MINOR_VERSION` to the minor version of the docs you want to build. For example,
if you want to build docs for Kubernetes 1.15, set `MINOR_VERSION` to 15. Save and close the `Makefile`.
* Set `K8S_ROOT` to `<k8s-base>`.
* Set `K8S_WEBROOT` to `<web-base>`.
* Set `K8S_RELEASE` to the minor 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.
-->
* 设置 `K8SROOT` 为 `<k8s-base>`.
* 设置 `WEBROOT` 为 `<web-base>`.
* 设置 `MINOR_VERSION` 为要构建的文档的次要版本。例如，如果您想为 Kubernetes 1.15 构建文档，请将 `MINOR_VERSION` 设置为 15。保存并关闭 `Makefile` 文件。
* 设置 `K8S_ROOT` 为 `<k8s-base>`.
* 设置 `K8S_WEBROOT` 为 `<web-base>`.
* 设置 `K8S_RELEASE` 为要构建的文档的版本。
例如，如果您想为 Kubernetes 1.17 构建文档，请将 `K8S_RELEASE` 设置为 1.17。
<!--
For example, update the following variables:
-->
例如，更新以下变量：
<!-- For example, update the following variables: -->
例如：
```
WEBROOT=$(GOPATH)/src/github.com/<your-username>/website
K8SROOT=$(GOPATH)/src/k8s.io/kubernetes
MINOR_VERSION=15
export K8S_WEBROOT=$(GOPATH)/src/github.com/<your-username>/website
export K8S_ROOT=$(GOPATH)/src/k8s.io/kubernetes
export K8S_RELEASE=1.17
```
<!--
### Copying the OpenAPI spec
-->
### 复制 OpenAPI 规范
### Creating versioned directory and fetching Open API spec
<!--
Run the following command in `<rdocs-base>`:
The `updateapispec` build target creates the versioned build directory.
After the directory is created, the Open API spec is fetched from the
`<k8s-base>` repository. These steps ensure that the version
of the configuration files and Kubernetes Open API spec match the release version.
The versioned directory name follows the pattern of `v<major>_<minor>`.
-->
在 `<rdocs-base>` 目录中运行以下命令：
### 创建版本目录并复制 OpenAPI 规范
构建目标 `updateapispec` 负责创建版本化的构建目录。
目录创建了之后，从 `<k8s-base>` 仓库取回 OpenAPI 规范文件。
这些步骤确保配置文件的版本和 Kubernetes OpenAPI 规范的版本与发行版本匹配。
版本化目录的名称形式为 `v<major>_<minor>`。
```shell
make updateapispec
```
<!--
The output shows that the file was copied:
-->
输出显示文件已被复制：
```shell
cp ~/src/k8s.io/kubernetes/api/openapi-spec/swagger.json gen-apidocs/generators/openapi-spec/swagger.json
```
<!--
### Building the API reference docs
The `copyapi` target builds the API reference and
copies the generated files to directories in `<web-base>`.
Run the following command in `<rdocs-base>`:
-->
### 构建 API 参考文档
<!--
Run the following command in `<rdocs-base>`:
-->
构建目标 `copyapi` 会生成 API 参考文档并将所生成文件复制到
`<web-base` 中的目录下。
在 `<rdocs-base>` 目录中运行以下命令：
```shell
make api
cd <rdocs-base>
make copyapi
```
<!--
Verify that these two files have been generated:
-->
<!-- Verify that these two files have been generated: -->
验证是否已生成这两个文件：
```shell
@ -223,108 +186,83 @@ Verify that these two files have been generated:
[ -e "<rdocs-base>/gen-apidocs/generators/build/navData.js" ] && echo "navData.js built" || echo "no navData.js"
```
<!--
### Creating directories for published docs
<!--
Go to the base of your local `<web-base>`, and
view which files have been modified:
-->
### 创建发布文档的目录
<!--
Create the directories in `<web-base>` for the generated API reference files:
-->
在 `<web-base>` 目录中为生成的 API 参考文件创建目录：
```shell
mkdir -p <web-base>/static/docs/reference/generated/kubernetes-api/v1.<minor-version>
mkdir -p <web-base>/static/docs/reference/generated/kubernetes-api/v1.<minor-version>/css
mkdir -p <web-base>/static/docs/reference/generated/kubernetes-api/v1.<minor-version>/fonts
```
<!--
## Copying the generated docs to the kubernetes/website repository
-->
## 将生成的文档复制到 kubernetes/website 仓库
<!--
Run the following command in `<rdocs-base>` to copy the generated files to
your local kubernetes/website repository:
-->
在 `<rdocs-base>` 目录中运行以下命令，将生成的文件复制到本地 kubernetes/website 仓库。
```shell
make copyapi
```
<!--
Go to the base of your local kubernetes/website repository, and
see which files have been modified:
-->
进入 kubernetes/website 仓库的本地主目录，并查看已修改的文件：
进入本地 `<web-base>` 目录，检查哪些文件被更改：
```shell
cd <web-base>
git status
```
<!--
The output shows the modified files:
-->
输出显示修改后的文件：
<!-- The output is similar to: -->
输出类似于：
```
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
```
<!--
## Updating the API reference index pages
When generating reference documentation for a new release, update the file,
`<web-base>/content/en/docs/reference/kubernetes-api/api-index.md` with the new
version number.
-->
## 更新 API 参考索引页面
在为新发行版本生成参考文档时，需要更新下面的文件，使之包含新的版本号：
`<web-base>/content/en/docs/reference/kubernetes-api/api-index.md`。
<!--
* Open `<web-base>/content/en/docs/reference/kubernetes-api/index.md` for editing, and update the API reference
version number. For example:
<!--
* Open `<web-base>/content/en/docs/reference/kubernetes-api/api-index.md` for editing,
and update the API reference version number. For example:
```
title: v1.17
[Kubernetes API v1.17](/docs/reference/generated/kubernetes-api/v1.17/)
```
-->
* 打开 `<web-base>/content/en/docs/reference/kubernetes-api/index.md` 文件进行编辑，并且更新 API 参考版本号。例如：
* 打开并编辑 `<web-base>/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/)
```
<!--
<!--
* Open `<web-base>/content/en/docs/reference/_index.md` for editing, and add a
new link for the latest API reference. Remove the oldest API reference version.
There should be five links to the most recent API references.
new link for the latest API reference. Remove the oldest API reference version.
There should be five links to the most recent API references.
-->
* 打开 `<web-base>/content/en/docs/reference/_index.md` 文件进行编辑，并添加新链接以获取最新的 API 参考。移除最旧的 API 参考版本。应该有五个指向最新 API 参考的链接。
* 打开编辑 `<web-base>/content/en/docs/reference/_index.md`，添加指向最新 API 参考
的链接，删除最老的 API 版本。
通常保留最近的五个版本的 API 参考的链接。
<!--
## Locally test the API reference
-->
## 在本地测试 API 参考
<!--
Publish a local version of the API reference.
Verify the [local preview](http://localhost:1313/docs/reference/generated/kubernetes-api/v1.15/).
-->
## 在本地测试 API 参考
发布 API 参考的本地版本。
验证 [本地预览](http://localhost:1313/docs/reference/generated/kubernetes-api/v1.15/)。
检查[本地预览](http://localhost:1313/docs/reference/generated/kubernetes-api/v1.15/)。
```shell
cd <web-base>
@ -333,11 +271,11 @@ make docker-serve
<!--
## Commit the changes
In `<web-base>` run `git add` and `git commit` to commit the change.
-->
## 提交更改
<!--
In `<web-base>` run `git add` and `git commit` to commit the change. -->
在 `<web-base>` 中运行 `git add` 和 `git commit` 来提交更改。
<!--
@ -347,19 +285,18 @@ Submit your changes as a
Monitor your pull request, and respond to reviewer comments as needed. Continue
to monitor your pull request until it has been merged.
-->
将您的更改[创建 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" %}}
<!--
* [Generating Reference Docs for Kubernetes Components and Tools](/docs/home/contribute/generated-reference/kubernetes-components/)
* [Generating Reference Documentation for kubectl Commands](/docs/home/contribute/generated-reference/kubectl/)
* [Generating Reference Documentation for the Kubernetes Federation API](/docs/home/contribute/generated-reference/federation-api/)
* [Generating Reference Documentation Quickstart](/docs/contribute/generate-ref-docs/quickstart/)
* [Generating Reference Docs for Kubernetes Components and Tools](/docs/contribute/generate-ref-docs/kubernetes-components/)
* [Generating Reference Documentation for kubectl Commands](/docs/contribute/generate-ref-docs/kubectl/)
-->
* [为 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/)

403
content/zh/docs/contribute/generate-ref-docs/kubernetes-components.md
View File

@ -1,413 +1,50 @@
---
title: 为 Kubernetes 组件和工具生成参考页面
title: 为 Kubernetes 组件和工具生成参考文档
content_type: task
weight: 120
---
<!--
---
title: Generating Reference Pages for Kubernetes Components and Tools
content_type: task
---
weight: 120
-->
<!-- overview -->
<!--
This page shows how to use the `update-imported-docs` tool to generate
reference documentation for tools and components in the
[Kubernetes](https://github.com/kubernetes/kubernetes) and
[Federation](https://github.com/kubernetes/federation) repositories.
This page shows how to build the Kubernetes component and tool reference pages.
-->
本页面展示了如何使用 `update-imported-docs` 工具来为 [Kubernetes](https://github.com/kubernetes/kubernetes) 和 [Federation](https://github.com/kubernetes/federation) 仓库中的工具和组件生成参考文档。
本页面描述如何构造 Kubernetes 组件和工具的参考文档。
## {{% heading "prerequisites" %}}
<!--
* You need a machine that is running Linux or macOS.
Start with the [Prerequisites section](/docs/contribute/generate-ref-docs/quickstart/#before-you-begin)
in the Reference Documentation Quickstart guide.
-->
* 你需要一个运行着 Linux 或 macOS 操作系统的机器。
<!--
* You need to have this software installed:
* [Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)
* [Golang](https://golang.org/doc/install) version 1.9 or later
* [make](https://www.gnu.org/software/make/)
* [gcc compiler/linker](https://gcc.gnu.org/)
-->
* 你需要安装以下软件：
* [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/)
<!--
* Your `$GOPATH` environment variable must be set.
-->
* 在环境变量中设置 `$GOPATH`。
<!--
* You need to know how to create a pull request to a GitHub repository.
Typically, this involves creating a fork of the repository. For more
information, see
[Creating a Documentation Pull Request](/docs/home/contribute/create-pull-request/).
-->
* 你需要知道如何在一个 GitHub 项目仓库中创建一个 PR。一般来说，这涉及到创建仓库的一个分支。想了解更多信息，请参见[创建一个文档 PR](/docs/home/contribute/create-pull-request/)。
阅读参考文档快速入门指南中的[准备工作](/docs/contribute/generate-ref-docs/quickstart/#before-you-begin)节。
<!-- steps -->
<!--
## Getting two repositories
Follow the [Reference Documentation Quickstart](/docs/contribute/generate-ref-docs/quickstart/)
to generate the Kubernetes component and tool reference pages.
-->
## 下载两个仓库
<!--
If you don't already have the `kubernetes/website` repository, get it now:
-->
如果你还没有下载过 `kubernetes/website` 仓库，现在下载：
```shell
mkdir $GOPATH/src
cd $GOPATH/src
go get github.com/kubernetes/website
```
<!--
Determine the base directory of your clone of the
[kubernetes/website](https://github.com/kubernetes/website) repository.
For example, if you followed the preceding step to get the repository,
your base directory is `$GOPATH/src/github.com/kubernetes/website.`
The remaining steps refer to your base directory as `<web-base>`.
-->
确定 [kubernetes/website](https://github.com/kubernetes/website) 仓库的本地主目录。例如，如果按照前面的步骤来获取该仓库，则主目录是 `$GOPATH/src/github.com/kubernetes/website`。下文将该目录称为 `<web-base>`。
<!--
If you plan on making changes to the ref docs, and if you don't already have
the `kubernetes/kubernetes` repository, get it now:
-->
如果你想对参考文档进行修改，但是你还没下载过 `kubernetes/kubernetes` 仓库，现在下载：
```shell
mkdir $GOPATH/src
cd $GOPATH/src
go get github.com/kubernetes/kubernetes
```
<!--
Determine the base directory of your clone of the
[kubernetes/kubernetes](https://github.com/kubernetes/kubernetes) repository.
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 `<k8s-base>`.
-->
确定 [kubernetes/kubernetes](https://github.com/kubernetes/kubernetes) 仓库的本地主目录。例如，如果按照前面的步骤来获取该仓库，则主目录是 `$GOPATH/src/github.com/kubernetes/kubernetes`。下文将该目录称为 `<k8s-base>`。
{{< note >}}
<!--
If you only need to generate, but not change, the reference docs, you don't need to
manually get the `kubernetes/kubernetes` repository. When you run the `update-imported-docs`
tool, it automatically clones the `kubernetes/kubernetes` repository.
-->
如果你只想生成参考文档，而不需要修改，则不需要手动下载 `kubernetes/kubernetes` 仓库。当你运行 `update-imported-docs` 工具时，它会自动克隆 `kubernetes/kubernetes` 仓库。
{{< /note >}}
<!--
## Editing the Kubernetes source code
-->
## 编辑 Kubernetes 源码
<!--
The reference documentation for the Kubernetes components and tools is automatically
generated from the Kubernetes source code. If you want to change the reference documentation,
the first step is to change one or more comments in the Kubernetes source code. Make the
change in your local kubernetes/kubernetes repository, and then submit a pull request to
the master branch of
[github.com/kubernetes/kubernetes](https://github.com/kubernetes/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)
is an example of a pull request that makes changes to comments in the Kubernetes
source code.
-->
[PR 56942](https://github.com/kubernetes/kubernetes/pull/56942) 是一个对 Kubernetes 源码中的注释进行修改的 PR 示例。
<!--
Monitor your pull request, and respond to reviewer comments. Continue to monitor
your pull request until it is merged into the master branch of the
`kubernetes/kubernetes` repository.
-->
跟踪你的 PR，并回应评审人的评论。继续跟踪你的 PR，直到它合入到 `kubernetes/kubernetes` 仓库的 master 分支中。
<!--
## Cherry picking your change into a release branch
-->
## 以 cherry-pick 方式将你的修改合入已发布分支
<!--
Your change is now in the master branch, which is used for development of the next
Kubernetes release. If you want your change to appear in the docs for a Kubernetes
version that has already been released, you need to propose that your change be cherry
picked into the release branch.
-->
你的修改已合入 master 分支中，该分支用于开发下一个 Kubernetes 版本。如果你希望修改部分出现在已发布的 Kubernetes 版本文档中，则需要提议将它们以 cherry-pick 方式合入已发布分支。
<!--
For example, suppose the master branch is being used to develop Kubernetes 1.10, and
you want to backport your change to the release-1.9 branch. For instructions on how
to do this, see
[Propose a Cherry Pick](https://github.com/kubernetes/community/blob/master/contributors/devel/cherry-picks.md).
-->
例如，假设 master 分支正用于开发 Kubernetes 1.10 版本，而你希望将修改合入到已发布的 1.9 版本分支。相关的操作指南，请参见 [提议一个 cherry-pick 合入](https://github.com/kubernetes/community/blob/master/contributors/devel/cherry-picks.md)。
<!--
Monitor your cherry-pick pull request until it is merged into the release branch.
-->
跟踪你的 cherry-pick PR，直到它合入到已发布分支中。
{{< note >}}
<!--
Proposing a cherry pick requires that you have permission to set a label
and a milestone in your pull request. If you don’t have those permissions, you will
need to work with someone who can set the label and milestone for you.
-->
提议一个 cherry-pick 合入，需要你有在 PR 中设置标签和里程碑的权限。如果你没有，你需要与有权限为你设置标签和里程碑的人合作完成。
{{< /note >}}
<!--
## Overview of update-imported-docs
-->
## update-imported-docs 概述
<!--
The `update-imported-docs` tool is located in the `kubernetes/website/update-imported-docs/`
directory. The tool performs the following steps:
-->
`update-imported-docs` 工具在 `kubernetes/website/update-imported-docs/` 目录下。它执行以下步骤：
<!--
1. Clones the related repositories specified in a configuration file. For the
purpose of generating reference docs, the repositories that are cloned by
default are `kubernetes-incubator/reference-docs` and `kubernetes/federation`.
1. Runs commands under the cloned repositories to prepare the docs generator and
then generates the Markdown files.
1. Copies the generated Markdown files to a local clone of the `kubernetes/website`
repository under locations specified in the configuration file.
-->
1. 克隆配置文件中指定的相关仓库。为了生成参考文档，默认情况下克隆的仓库是 `kubernetes-incubator/reference-docs` 和 `kubernetes/federation`。
1. 在克隆出的仓库下运行命令来准备文档生成器，然后生成 Markdown 文件。
1. 将生成的 Markdown 文件复制到配置文件中指定的 `kubernetes/website` 仓库的本地目录中。
<!--
When the Markdown files are in your local clone of the `kubernetes/website`
repository, you can submit them in a
[pull request](/docs/home/contribute/create-pull-request/)
to `kubernetes/website`.
-->
当 Markdown 文件放入 `kubernetes/website` 仓库的本地目录中后，你就可以创建 [PR](/docs/home/contribute/create-pull-request/) 将它们提交到 `kubernetes/website`。
<!--
## Customizing the reference.yml config file
-->
## 自定义 reference.yml 配置文件
<!--
Open `<web-base>/update-imported-docs/reference.yml` for editing.
Do not change the content for the `generate-command` entry unless you understand
what it is doing and need to change the specified release branch.
-->
打开 `<web-base>/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
```
<!--
In reference.yml, the `files` field is a list of `src` and `dst` fields. The `src` field
specifies the location of a generated Markdown file, and the `dst` field specifies
where to copy this file in the cloned `kubernetes/website` repository.
For example:
-->
在 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
...
```
<!--
Note that when there are many files to be copied from the same source directory
to the same destination directory, you can use wildcards in the value given to
`src` and you can just provide the directory name as the value for `dst`.
For example:
-->
注意，当有许多文件要从同一个源目录复制到同一个目标目录时，可以使用通配符给 `src` 赋值，而使用目录名给 `dst` 赋值。例如：
```shell
files:
- src: gen-compdocs/build/kubeadm*.md
dst: content/en/docs/reference/setup-tools/kubeadm/generated/
```
<!--
## Running the update-imported-docs tool
-->
## 运行 update-imported-docs 工具
<!--
After having reviewed and/or customized the `reference.yaml` file, you can run
the `update-imported-docs` tool:
-->
在检查与或自定义 `reference.yaml` 文件后，运行 `update-imported-docs` 工具：
```shell
cd <web-base>/update-imported-docs
./update-imported-docs reference.yml
```
<!--
## Adding and committing changes in kubernetes/website
-->
## 在 kubernetes/website 中添加和提交修改
<!--
List the files that were generated and copied to the `kubernetes/website`
repository:
-->
列出生成并准备合入到 `kubernetes/website` 仓库中的文件：
```
cd <web-base>
git status
```
<!--
The output shows the new and modified files. For example, the output
might look like this:
-->
输出展示了新增和修改的文件。例如，输出可能如下所示：
```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
...
```
<!--
Run `git add` and `git commit` to commit the files.
-->
运行 `git add` 和 `git commit` 将提交上述文件。
<!--
## Creating a pull request
-->
## 创建 PR
<!--
Create a pull request to the `kubernetes/website` repository. Monitor your
pull request, and respond to review comments as needed. Continue to monitor
your pull request until it is merged.
-->
对 `kubernetes/website` 仓库创建 PR。跟踪你的 PR，并根据需要回应评审人的评论。继续跟踪你的 PR，直到它被合入。
<!--
A few minutes after your pull request is merged, your updated reference
topics will be visible in the
[published documentation](/docs/home/).
-->
在 PR 合入的几分钟后，你更新的参考主题将出现在[已发布文档](/docs/home/)中。
按照[参考文档快速入门](/docs/contribute/generate-ref-docs/quickstart/)
指引，生成 Kubernetes 组件和工具的参考文档。
## {{% heading "whatsnext" %}}
<!--
* [Generating Reference Documentation for kubectl Commands](/docs/home/contribute/generated-reference/kubectl/)
* [Generating Reference Documentation for the Kubernetes API](/docs/home/contribute/generated-reference/kubernetes-api/)
* [Generating Reference Documentation for the Kubernetes Federation API](/docs/home/contribute/generated-reference/federation-api/)
* [Generating Reference Documentation Quickstart](/docs/contribute/generate-ref-docs/quickstart/)
* [Generating Reference Documentation for kubectl Commands](/docs/contribute/generate-ref-docs/kubectl/)
* [Generating Reference Documentation for the Kubernetes API](/docs/contribute/generate-ref-docs/kubernetes-api/)
* [Contributing to the Upstream Kubernetes Project for Documentation](/docs/contribute/generate-ref-docs/contribute-upstream/)
-->
* [为 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/)

45
content/zh/docs/contribute/generate-ref-docs/prerequisites-ref-docs.md Normal file
View File

@ -0,0 +1,45 @@
<!--
### Requirements:
- You need a machine that is running Linux or macOS.
- You need to have these tools installed:
- [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) version 1.13+
- [Pip](https://pypi.org/project/pip/) used to install PyYAML
- [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/) (Required only for `kubectl` command reference)
-->
### 需求 {#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` 命令参考）
<!--
- Your `PATH` environment variable must include the required build tools, such as the `Go` binary and `python`.
- You need to know how to create a pull request to a GitHub repository.
This involves creating your own fork of the repository. For more
information, see [Work from a local clone](/docs/contribute/intermediate/#work_from_a_local_clone).
-->
- 你的 `PATH` 环境变量必须包含所需要的构建工具，例如 `Go` 程序和 `python`。
- 你需要知道如何为一个 GitHub 仓库创建拉取请求（PR）。
这牵涉到创建仓库的派生（fork）副本。
有关信息可进一步查看[基于本地副本开展工作](/docs/contribute/intermediate/#work_from_a_local_clone)。

405
content/zh/docs/contribute/generate-ref-docs/quickstart.md Normal file
View File

@ -0,0 +1,405 @@
---
title: 快速入门
content_type: task
weight: 40
---
<!--
title: Quickstart
content_type: task
weight: 40
-->
<!-- overview -->
<!--
This page shows how to use the `update-imported-docs` script to generate
the Kubernetes reference documentation. The script automates
the build setup and generates the reference documentation for a release.
-->
本页讨论如何使用 `update-imported-docs` 脚本来生成 Kubernetes 参考文档。
此脚本将构建的配置过程自动化，并为某个发行版本生成参考文档。
## {{% heading "prerequisites" %}}
{{< include "prerequisites-ref-docs.md" >}}
<!-- steps -->
<!--
## Getting the docs repository
Make sure your `website` fork is up-to-date with the `kubernetes/website` master and clone
your `website` fork.
-->
## 获取文档仓库 {#getting-the-docs-repository}
确保你的 `website` 派生仓库与 `kubernetes/website` 主分支一致，并克隆
你的派生仓库。
```shell
mkdir github.com
cd github.com
git clone git@github.com:<your_github_username>/website.git
```
<!--
Determine the base directory of your clone. For example, if you followed the
preceding step to get the repository, your base directory is
`github.com/website.` The remaining steps refer to your base directory as
`<web-base>`.
{{< note>}}
If you want to change the content of the component tools and API reference,
see the [contributing upstream guide](/docs/contribute/generate-ref-docs/contribute-upstream).
{{< /note >}}
-->
确定你的克隆副本的根目录。例如，如果你按照前面的步骤获取了仓库，你的根目录
会是 `github.com/website`。接下来的步骤中，`<web-base>` 用来指代你的根目录。
{{< note>}}
如果你希望更改构建工具和 API 参考资料，可以阅读
[上游贡献指南](/docs/contribute/generate-ref-docs/contribute-upstream).
{{< /note >}}
<!--
## Overview of update-imported-docs
The `update-imported-docs` script is located in the `<web-base>/update-imported-docs/`
directory.
The script builds the following references:
* Component and tool reference pages
* The `kubectl` command reference
* The Kubernetes API reference
-->
## update-imported-docs 的概述
脚本 `update-imported-docs` 位于 `<web-base>/update-imported-docs/` 目录下，
能够生成以下参考文档：
* Kubernetes 组件和工具的参考页面
* `kubectl` 命令参考文档
* Kubernetes API 参考文档
<!--
The `update-imported-docs` script generates the Kubernetes reference documentation
from the Kubernetes source code. The script creates a temporary directory
under `/tmp` on your machine and clones the required repositories: `kubernetes/kubernetes` and
`kubernetes-sigs/reference-docs` into this directory.
The script sets your `GOPATH` to this temporary directory.
Three additional environment variables are set:
* `K8S_RELEASE`
* `K8S_ROOT`
* `K8S_WEBROOT`
-->
脚本 `update-imported-docs` 基于 Kubernetes 源代码生成参考文档。
过程中会在你的机器的 `/tmp` 目录下创建临时目录，克隆所需要的仓库
`kubernetes/kubernetes` 和 `kubernetes-sigs/reference-docs` 到此临时目录。
脚本会将 `GOPATH` 环境变量设置为指向此临时目录。
此外，脚本会设置三个环境变量：
* `K8S_RELEASE`
* `K8S_ROOT`
* `K8S_WEBROOT`
<!--
The script requires two arguments to run successfully:
* A YAML configuration file (`reference.yml`)
* A release version, for example:`1.17`
The configuration file contains a `generate-command` field.
The `generate-command` field defines a series of build instructions
from `kubernetes-sigs/reference-docs/Makefile`. The `K8S_RELEASE` variable
determines the version of the release.
-->
脚本需要两个参数才能成功运行：
* 一个 YAML 配置文件（`reference.yml`）
* 一个发行版本字符串，例如：`1.17`
配置文件中包含 `generate-command` 字段，其中定义了一系列来自于
`kubernetes-sigs/reference-docs/Makefile` 的构建指令。
变量 `K8S_RELEASE` 用来确定所针对的发行版本。
<!--
The `update-imported-docs` script performs the following steps:
1. Clones the related repositories specified in a configuration file. For the
purpose of generating reference docs, the repository that is cloned by
default is `kubernetes-sigs/reference-docs`.
1. Runs commands under the cloned repositories to prepare the docs generator and
then generates the HTML and Markdown files.
1. Copies the generated HTML and Markdown files to a local clone of the `<web-base>`
repository under locations specified in the configuration file.
1. Updates `kubectl` command links from `kubectl`.md to the refer to
the sections in the `kubectl` command reference.
-->
脚本 `update-imported-docs` 执行以下步骤：
1. 克隆配置文件中所指定的相关仓库。就生成参考文档这一目的而言，要克隆的
仓库默认为 `kubernetes-sigs/reference-docs`。
1. 在所克隆的仓库下运行命令，准备文档生成器，之后生成 HTML 和 Markdown 文件。
1. 将所生成的 HTML 和 Markdown 文件复制到 `<web-base>` 本地克隆副本中，
放在配置文件中所指定的目录下。
1. 更新 `kubectl.md` 文件中对 `kubectl` 命令文档的链接，使之指向 `kubectl`
命令参考中对应的节区。
<!--
When the generated files are in your local clone of the `<web-base>`
repository, you can submit them in a [pull request](/docs/contribute/start/)
to `<web-base>`.
-->
当所生成的文件已经被放到 `<web-base>` 目录下，你就可以将其提交到你的派生副本中，
并基于所作提交发起[拉取请求（PR）](/docs/contribute/start/)到 k/website 仓库。
<!--
## Configuration file format
Each configuration file may contain multiple repos that will be imported together. When
necessary, you can customize the configuration file by manually editing it. You
may create new config files for importing other groups of documents.
The following is an example of the YAML configuration file:
-->
## 配置文件格式 {#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
```
<!--
Single page Markdown documents, imported by the tool, must adhere to
the [Documentation Style Guide](/docs/contribute/style/style-guide/).
-->
通过工具导入的单页面的 Markdown 文档必须遵从
[文档样式指南](/docs/contribute/style/style-guide/)。
<!--
## Customizing reference.yml
Open `<web-base>/update-imported-docs/reference.yml` for editing.
Do not change the content for the `generate-command` field unless you understand
how the command is used to build the references.
You should not need to update `reference.yml`. At times, changes in the
upstream source code, may require changes to the configuration file
(for example: golang version dependencies and third-party library changes).
If you encounter build issues, contact the SIG-Docs team on the
[#sig-docs Kubernetes Slack channel](https://kubernetes.slack.com).
-->
## 定制 reference.yml
打开 `<web-base>/update-imported-docs/reference.yml` 文件进行编辑。
在不了解参考文档构造命令的情况下，不要更改 `generate-command` 字段的内容。
你一般不需要更新 `reference.yml` 文件。不过也有时候上游的源代码发生变化，
导致需要对配置文件进行更改（例如：Golang 版本依赖或者第三方库发生变化）。
如果你遇到类似问题，请在 [Kubernetes Slack 的 #sig-docs 频道](https://kubernetes.slack.com)
联系 SIG-Docs 团队。
<!--
{{< note >}}
The `generate-command` is an optional entry, which can be used to run a
given command or a short script to generate the docs from within a repository.
{{< /note >}}
In `reference.yml`, `files` contains a list of `src` and `dst` fields.
The `src` field contains the location of a generated Markdown file in the cloned
`kubernetes-sigs/reference-docs` build directory, and the `dst` field specifies
where to copy this file in the cloned `kubernetes/website` repository.
For example:
-->
{{< 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
...
```
<!--
Note that when there are many files to be copied from the same source directory
to the same destination directory, you can use wildcards in the value given to
`src`. You must provide the directory name as the value for `dst`.
For example:
-->
注意，如果从同一源目录中有很多文件要复制到目标目录，你可以在为 `src` 所设置的
值中使用通配符。这时，为 `dst` 所设置的值必须是目录名称。例如：
```yaml
files:
- src: gen-compdocs/build/kubeadm*.md
dst: content/en/docs/reference/setup-tools/kubeadm/generated/
```
<!--
## Running the update-imported-docs tool
You can run the `update-imported-docs` tool as follows:
-->
## 运行 update-imported-docs 工具
你可以用如下方式运行 `update-imported-docs` 工具：
```shell
cd <web-base>/update-imported-docs
./update-imported-docs <configuration-file.yml> <release-version>
```
<!-- For example: -->
例如：
```shell
./update-imported-docs reference.yml 1.17
```
<!-- Revisit: is the release configuration used -->
<!-- ## Fixing Links
The `release.yml` configuration file contains instructions to fix relative links.
To fix relative links within your imported files, set the`gen-absolute-links`
property to `true`. You can find an example of this in
[`release.yml`](https://github.com/kubernetes/website/blob/master/update-imported-docs/release.yml).
-->
## 修复链接
配置文件 `release.yml` 中包含用来修复相对链接的指令。
若要修复导入文件中的相对链接，将 `gen-absolute-links` 属性设置为 `true`。
你可以在 [`release.yml`](https://github.com/kubernetes/website/blob/master/update-imported-docs/release.yml)
文件中找到示例。
<!--
## Adding and committing changes in kubernetes/website
List the files that were generated and copied to `<web-base>`:
-->
## 添加并提交 kubernetes/website 中的变更
枚举新生成并复制到 `<web-base>` 的文件：
```shell
cd <web-base>
git status
```
<!--
The output shows the new and modified files. The generated output varies
depending upon changes made to the upstream source code.
### Generated component tool files
-->
输出显示新生成和已修改的文件。取决于上游源代码的修改多少，
所生成的输出也会不同。
### 生成的 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
```
<!-- ### Generated kubectl command reference files -->
### 生成的 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
```
<!-- ### Generated Kubernetes API reference directories and files -->
### 生成的 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
```
<!--
Run `git add` and `git commit` to commit the files.
## Creating a pull request
Create a pull request to the `kubernetes/website` repository. Monitor your
pull request, and respond to review comments as needed. Continue to monitor
your pull request until it is merged.
A few minutes after your pull request is merged, your updated reference
topics will be visible in the
[published documentation](/docs/home/).
-->
运行 `git add` 和 `git commit` 提交文件。
## 创建拉取请求 {#creating-a-pull-request}
接下来创建一个对 `kubernetes/website` 仓库的拉取请求（PR）。
监视所创建的 PR，并根据需要对评阅意见给出反馈。
继续监视该 PR 直到其被合并为止。
当你的 PR 被合并几分钟之后，你所做的对参考文档的变更就会出现
[发布的文档](/docs/home/)上。
## {{% heading "whatsnext" %}}
<!--
To generate the individual reference documentation by manually setting up the required build repositories and
running the build targets, see the following guides:
* [Generating Reference Documentation for Kubernetes Components and Tools](/docs/contribute/generate-ref-docs/kubernetes-components/)
* [Generating Reference Documentation for kubectl Commands](/docs/contribute/generate-ref-docs/kubectl/)
* [Generating Reference Documentation for the Kubernetes API](/docs/contribute/generate-ref-docs/kubernetes-api/)
-->
要手动设置所需的构造仓库，执行构建目标，以生成各个参考文档，可参考下面的指南：
* [为 Kubernetes 组件和工具生成参考文档](/docs/contribute/generate-ref-docs/kubernetes-components/)
* [为 kubeclt 命令生成参考文档](/docs/contribute/generate-ref-docs/kubectl/)
* [为 Kubernetes API 生成参考文档](/docs/contribute/generate-ref-docs/kubernetes-api/)