whentimeslows/website
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Switch language name 'zh' to 'zh-cn'

Browse Source 
This is the first step to rename 'zh' to 'zh-cn'. There are several reasons why we rename the language name.

- The upstream docsy theme changed the language name, leading to many warnings during site build;
  The side-effect is that the i18n strings are no longer working.
- We believe renaming the language is the right thing to do, because this move can make room for other variants of Chinese language, such as 'zh-tw', 'zh-sg' etc.

There would be several follow-ups to this PR, such as fixing the intra-site links, adding redirects etc.

We will lock up changes to zh/zh-cn pages for the moment, until this one gets in.

This PR is based on commit cdad0a7342.
This commit is contained in:
Qiming Teng
2022-06-10 20:25:27 +08:00
parent 3d345b1816
commit c52818c03d
1347 changed files with 8 additions and 6 deletions
Download Patch File Download Diff File Expand all files Collapse all files
content/zh-cn/docs/contribute/generate-ref-docs/_index.md
+26
View File
@@ -0,0 +1,26 @@
---
title: 参考文档概述
main_menu: true
weight: 80
---
<!--
title: Reference docs overview
main_menu: true
weight: 80
-->
<!--
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 参考指南。
要生成参考文档，请参考下面的指南：
* [生成参考文档快速入门](/zh/docs/contribute/generate-ref-docs/quickstart/)
content/zh-cn/docs/contribute/generate-ref-docs/contribute-upstream.md
+423
View File
@@ -0,0 +1,423 @@
---
title: 为上游 Kubernetes 代码库做出贡献
content_type: task
weight: 20
---
<!--
title: Contributing to the Upstream Kubernetes Code
content_type: task
weight: 20
-->
<!-- overview -->
<!--
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
文档或 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:
- [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 的参考文档](/zh/docs/contribute/generate-ref-docs/kubernetes-api/)
- [生成 Kubernetes 组件和工具的参考文档](/zh/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/)
- [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)
- [Golang](https://golang.org/doc/install) 的 1.13 版本或更高
- [Docker](https://docs.docker.com/engine/installation/)
- [etcd](https://github.com/coreos/etcd/)
- [make](https://www.gnu.org/software/make/)
- [gcc compiler/linker](https://gcc.gnu.org/)
<!--
- Your $GOPATH environment variable must be set, and the location of `etcd`
must be in your $PATH environment variable.
-->
- 你必须设置 `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 标准派生和 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/).
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 代码仓库
如果你还没有 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>`。
<!--
Determine the base directory of your clone of the
[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-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>`。
<!--
## Editing the Kubernetes source code
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 源代码
Kubernetes API 参考文档是根据 OpenAPI 规范自动生成的，该规范是从 Kubernetes 源代码生成的。
如果要更改 API 参考文档，第一步是更改 Kubernetes 源代码中的一个或多个注释。
<!--
The documentation for the `kube-*` components is also generated from the upstream
source code. You must change the code related to the component
you want to fix in order to fix the generated documentation.
-->
`kube-*` 组件的文档也是从上游源代码生成的。你必须更改与要修复的组件相关的代码，才能修复生成的文档。
<!--
### Making changes to the upstream source code
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.
In your local kubernetes/kubernetes repository, check out the default branch,
and make sure it is up to date:
-->
以下在 Kubernetes 源代码中编辑注释的示例。
在你本地的 kubernetes/kubernetes 代码仓库中，检出默认分支，并确保它是最新的：
```shell
cd <k8s-base>
git checkout master
git pull https://github.com/kubernetes/kubernetes master
```
<!--
Suppose this source file in that default branch has the typo "atmost":
-->
假设默认分支中的下面源文件中包含拼写错误 "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".
Verify that you have changed the file:
-->
在你的本地环境中，打开 `types.go` 文件，然后将 "atmost" 更改为 "at most"。
以下命令验证你已经更改了文件：
```shell
git status
```
<!--
The output shows that you are on the master branch, and that the `types.go`
source file has been modified:
-->
输出显示你在 master 分支上，`types.go` 源文件已被修改：
```shell
On branch master
...
modified: staging/src/k8s.io/api/apps/v1/types.go
```
<!--
### 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` 命令提交到目前为止所做的更改。
在下一步中，你将进行第二次提交，将更改分成两个提交很重要。
<!--
### Generating the OpenAPI spec and related files
Go to `<k8s-base>` and run these scripts:
-->
### 生成 OpenAPI 规范和相关文件
进入 `<k8s-base>` 目录并运行以下脚本：
```shell
hack/update-generated-swagger-docs.sh
hack/update-openapi-spec.sh
hack/update-generated-protobuf.sh
```
<!-- Run `git status` to see what was generated. -->
运行 `git status` 命令查看生成的文件。
```none
On branch master
...
modified: api/openapi-spec/swagger.json
modified: api/openapi-spec/v3/apis__apps__v1_openapi.json
modified: pkg/generated/openapi/zz_generated.openapi.go
modified: staging/src/k8s.io/api/apps/v1/generated.proto
modified: staging/src/k8s.io/api/apps/v1/types_swagger_doc_generated.go
```
<!--
View the contents of `api/openapi-spec/swagger.json` to make sure the typo is fixed.
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` 的内容，以确保拼写错误已经被修正。
例如，你可以运行 `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` 命令来提交你的更改。现在你有两个提交（commits）：
一种包含编辑的 `types.go` 文件，另一种包含生成的 OpenAPI 规范和相关文件。
将这两个提交分开独立。也就是说，不要 squash 你的提交。
<!--
Submit your changes as a
[pull request](https://help.github.com/articles/creating-a-pull-request/) to the
master branch of the
[kubernetes/kubernetes](https://github.com/kubernetes/kubernetes) repository.
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 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
源代码中的拼写错误的拉取请求的示例。
<!--
It can be tricky to determine the correct source file to be changed. In the
preceding example, the authoritative source file is in the `staging` directory
in the `kubernetes/kubernetes` repository. But in your situation,the `staging` directory
might not be the place to find the authoritative source. For guidance, check the
`README` files in
[kubernetes/kubernetes](https://github.com/kubernetes/kubernetes/tree/master/staging)
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` 文件。
{{< /note >}}
<!--
### Cherry picking your commit into a release branch
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 {{< skew latestVersion >}}, and you want to backport your change into the
release-{{< skew prevMinorVersion >}} branch.
-->
### 将你的提交 Cherrypick 到发布分支
在上一节中，你在 master 分支中编辑了一个文件，然后运行了脚本用来生成 OpenAPI 规范和相关文件。
然后用 PR 将你的更改提交到 kubernetes/kubernetes 代码仓库的 master 分支中。
现在，需要将你的更改反向移植到已经发布的分支。
例如，假设 master 分支被用来开发 Kubernetes {{< skew latestVersion >}} 版，
并且你想将更改反向移植到 release-{{< skew prevMinorVersion >}} 分支。
<!--
Recall that your pull request has two commits: one for editing `types.go`
and one for the files generated by scripts. The next step is to propose a cherry pick of your first
commit into the release-{{< skew prevMinorVersion >}} branch. The idea is to cherry pick the commit
that edited `types.go`, but not 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).
-->
回想一下，你的 PR 有两个提交：一个用于编辑 `types.go`，一个用于由脚本生成的文件。
下一步是将你的第一次提交 cherrypick 到 release-{{< skew prevMinorVersion >}} 分支。
这样做的原因是仅 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
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.
-->
{{< note >}}
提出 Cherry Pick 要求你有权在 PR 中设置标签和里程碑。如果你没有这些权限，
则需要与可以为你设置标签和里程碑的人员合作。
{{< /note >}}
<!--
When you have a pull request in place for cherry picking your one commit into the
release-{{< skew prevMinorVersion >}} branch, the next step is to run these scripts in the
release-{{< skew prevMinorVersion >}} branch of your local environment.
-->
当你发起 PR 将你的一个提交 cherry pick 到 release-{{< skew prevMinorVersion >}} 分支中时，
下一步是在本地环境的 release-{{< skew prevMinorVersion >}} 分支中运行如下脚本。
```shell
hack/update-generated-swagger-docs.sh
hack/update-openapi-spec.sh
hack/update-generated-protobuf.sh
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-{{< skew prevMinorVersion >}} branch.
-->
现在将提交添加到你的 Cherry-Pick PR 中，该 PR 中包含最新生成的 OpenAPI 规范和相关文件。
关注你的 PR，直到其合并到 release-{{< skew prevMinorVersion >}} 分支中为止。
<!--
At this point, both the master branch and the release-{{< skew prevMinorVersion >}} branch have your updated `types.go`
file and a set of generated files that reflect the change you made to `types.go`. Note that the
generated OpenAPI spec and other generated files in the release-{{< skew prevMinorVersion >}} branch are not necessarily
the same as the generated files in the master branch. The generated files in the release-{{< skew prevMinorVersion >}} branch
contain API elements only from Kubernetes {{< skew prevMinorVersion >}}. The generated files in the master branch might contain
API elements that are not in {{< skew prevMinorVersion >}}, but are under development for {{< skew latestVersion >}}.
-->
此时，master 分支和 release-{{< skew prevMinorVersion >}}
分支都具有更新的 `types.go` 文件和一组生成的文件，
这些文件反映了对 `types.go` 所做的更改。
请注意，生成的 OpenAPI 规范和其他 release-{{< skew prevMinorVersion >}}
分支中生成的文件不一定与 master 分支中生成的文件相同。
release-{{< skew prevMinorVersion >}} 分支中生成的文件仅包含来自
Kubernetes {{< skew prevMinorVersion >}} 的 API 元素。
master 分支中生成的文件可能包含不在 {{< skew prevMinorVersion >}}
中但正在为 {{< skew latestVersion >}} 开发的 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 参考文档。
<!--
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 的参考文档](/zh/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/)
* [Generating Reference Documentation for kubectl Commands](/docs/home/contribute/generated-reference/kubectl/)
-->
* [生成 Kubernetes API 的参考文档](/zh/docs/contribute/generate-ref-docs/kubernetes-api/)
* [为 Kubernetes 组件和工具生成参考文档](/zh/docs/contribute/generate-ref-docs/kubernetes-components/)
* [生成 kubectl 命令的参考文档](/zh/docs/contribute/generate-ref-docs/kubectl/)
content/zh-cn/docs/contribute/generate-ref-docs/kubectl.md
+431
View File
@@ -0,0 +1,431 @@
---
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 generate the `kubectl` command reference.
-->
本页面描述了如何生成 `kubectl` 命令参考。
<!--
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).
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/).
-->
{{< 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-commands/) 组件选项的参考页面。
相关说明请参见[为 Kubernetes 组件和工具生成参考页面](/zh/docs/contribute/generate-ref-docs/kubernetes-components/)。
{{< /note >}}
## {{% heading "prerequisites" %}}
{{< include "prerequisites-ref-docs.md" >}}
<!-- steps -->
<!--
## Setting up the local repositories
Create a local workspace and set your `GOPATH`.
-->
## 配置本地仓库
创建本地工作区并设置你的 `GOPATH`。
```shell
mkdir -p $HOME/<workspace>
export GOPATH=$HOME/<workspace>
```
<!-- Get a local clone of the following repositories: -->
获取以下仓库的本地克隆：
```shell
go get -u github.com/spf13/pflag
go get -u github.com/spf13/cobra
go get -u gopkg.in/yaml.v2
go get -u kubernetes-incubator/reference-docs
```
<!--
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：
```shell
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 软件包。
```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. -->
kubernetes/kubernetes 仓库提供对 kubectl 和 kustomize 源代码的访问。
<!--
* 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/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>`。
<!--
* 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/<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>`。
<!--
* Determine the base directory of your clone of the
[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-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>`。
<!--
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 {{< skew prevMinorVersion >}}.0, you could use these commands:
-->
在本地的 k8s.io/kubernetes 仓库中，检出感兴趣的分支并确保它是最新的。例如，
如果你想要生成 Kubernetes {{< skew prevMinorVersion >}}.0 的文档，可以使用以下命令：
```shell
cd <k8s-base>
git checkout v{{< skew prevMinorVersion >}}.0
git pull https://github.com/kubernetes/kubernetes {{< skew prevMinorVersion >}}.0
```
<!--
If you do not need to edit the kubectl source code, follow the instructions to
[Setting build variables](#setting-build-variables).
-->
如果不需要编辑 `kubectl`
源码，请按照说明[配置构建变量](#setting-build-variables)。
<!--
## Editing the kubectl source code
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。
<!--
[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.
Monitor your pull request, and respond to reviewer comments. Continue to monitor your
pull request until it is merged into the target branch of the kubernetes/kubernetes repository.
-->
[PR 56673](https://github.com/kubernetes/kubernetes/pull/56673/files) 是一个对 kubectl
源码中的笔误进行修复的 PR 示例。
跟踪你的 PR，并回应评审人的评论。继续跟踪你的 PR，直到它合入到 kubernetes/kubernetes 仓库的目标分支中。
<!--
## Cherry picking your change into a release branch
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 方式合入已发布分支。
<!--
For example, suppose the master branch is being used to develop Kubernetes
{{< skew currentVersion >}}
and you want to backport your change to the release-{{< skew prevMinorVersion >}} 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).
Monitor your cherry-pick pull request until it is merged into the release branch.
-->
例如，假设 master 分支正用于开发 Kubernetes {{< skew currentVersion >}} 版本，
而你希望将修改合入到 release-{{< skew prevMinorVersion >}} 版本分支。
相关的操作指南，请参见
[提议一个 cherry-pick](https://git.k8s.io/community/contributors/devel/sig-release/cherry-picks.md)。
跟踪你的 cherry-pick PR，直到它合入到已发布分支中。
<!--
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.
-->
{{< note >}}
提议一个 cherry-pick 需要你有在 PR 中设置标签和里程碑的权限。
如果你没有，你需要与有权限为你设置标签和里程碑的人合作完成。
{{< /note >}}
<!--
## Setting build variables
Go to `<rdocs-base>`, and open the `Makefile` for editing:
-->
## 设置构建变量 {#setting-build-variables}
进入 `<rdocs-base>` 目录, 打开 `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 {{< skew prevMinorVersion >}}, set `K8S_RELEASE` to {{< skew prevMinorVersion >}}.
For example, update the following variables:
-->
* 设置 `K8S_ROOT` 为 `<k8s-base>`。
* 设置 `K8S_WEBROOT` 为 `<web-base>`。
* 设置 `K8S_RELEASE` 为要构建文档的版本。
例如，如果你想为 Kubernetes {{< skew prevMinorVersion >}} 构建文档，
请将 `K8S_RELEASE` 设置为 {{< skew prevMinorVersion >}}。
例如：
```
export K8S_WEBROOT=$(GOPATH)/src/github.com/<your-username>/website
export K8S_ROOT=$(GOPATH)/src/k8s.io/kubernetes
export K8S_RELEASE={{< skew prevMinorVersion >}}
```
<!--
## 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
```
-->
## 创建版本目录
构建目标 `createversiondirs` 会生成一个版本目录并将 kubectl 参考配置文件复制到该目录中。
版本目录的名字模式为 `v<major>_<minor>`。
在 `<rdocs-base>` 目录下，执行下面的命令：
```shell
cd <rdocs-base>
make createversiondirs
```
<!--
## Checking out a branch in k8s.io/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 {{< skew prevMinorVersion >}}.0, checkout the `v{{< skew prevMinorVersion >}}` tag. Make sure
you local branch is up to date.
-->
## 从 kubernetes/kubernetes 检出一个分支
在本地 `<k8s-base>` 仓库中，检出你想要生成文档的、包含 Kubernetes 版本的分支。
例如，如果希望为 Kubernetes {{< skew prevMinorVersion >}}.0 版本生成文档，
请检出 `v{{< skew prevMinorVersion >}}` 标记。
确保本地分支是最新的。
```shell
cd <k8s-base>
git checkout v{{< skew prevMinorVersion >}}.0
git pull https://github.com/kubernetes/kubernetes v{{< skew prevMinorVersion >}}.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:
-->
## 运行文档生成代码
在本地的 `<rdocs-base>` 目录下，运行 `copycli` 构建目标。此命令以 `root` 账号运行：
```shell
cd <rdocs-base>
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>`。
<!--
## Locate the generated files
Verify that these two files have been generated:
-->
## 找到生成的文件
验证是否已生成以下两个文件：
```shell
[ -e "<rdocs-base>/gen-kubectldocs/generators/build/index.html" ] && echo "index.html built" || echo "no index.html"
[ -e "<rdocs-base>/gen-kubectldocs/generators/build/navData.js" ] && echo "navData.js built" || echo "no navData.js"
```
<!--
## Locate the copied files
Verify that all generated files have been copied to your `<web-base>`:
-->
## 找到复制的文件
确认所有生成的文件都已复制到你的 `<web-base>`：
```shell
cd <web-base>
git status
```
<!-- The output should include the modified files: -->
输出应包括修改后的文件：
```
static/docs/reference/generated/kubectl/kubectl-commands.html
static/docs/reference/generated/kubectl/navData.js
```
<!-- Additionally, the output might show the modified files: -->
此外，输出可能还包含：
```
static/docs/reference/generated/kubectl/scroll.js
static/docs/reference/generated/kubectl/stylesheet.css
static/docs/reference/generated/kubectl/tabvisibility.js
static/docs/reference/generated/kubectl/node_modules/bootstrap/dist/css/bootstrap.min.css
static/docs/reference/generated/kubectl/node_modules/highlight.js/styles/default.css
static/docs/reference/generated/kubectl/node_modules/jquery.scrollto/jquery.scrollTo.min.js
static/docs/reference/generated/kubectl/node_modules/jquery/dist/jquery.min.js
static/docs/reference/generated/kubectl/node_modules/font-awesome/css/font-awesome.min.css
```
<!--
## Locally test the documentation
Build the Kubernetes documentation in your local `<web-base>`.
-->
## 在本地测试文档
在本地 `<web-base>` 中构建 Kubernetes 文档。
```shell
cd <web-base>
git submodule update --init --recursive --depth 1 # if not already done
make container-serve
```
<!-- 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 中添加和提交更改
运行 `git add` 和 `git commit` 提交修改文件。
<!--
## 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).
-->
## 创建 PR
对 `kubernetes/website` 仓库创建 PR。跟踪你的 PR，并根据需要回应评审人的评论。
继续跟踪你的 PR，直到它被合入。
在 PR 合入的几分钟后，你更新的参考主题将出现在[已发布文档](/zh/docs/home/)中。
## {{% heading "whatsnext" %}}
<!--
* [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/)
-->
* [生成参考文档快速入门](/zh/docs/contribute/generate-ref-docs/quickstart/)
* [为 Kubernetes 组件和工具生成参考文档](/zh/docs/contribute/generate-ref-docs/kubernetes-components/)
* [为 Kubernetes API 生成参考文档](/zh/docs/contribute/generate-ref-docs/kubernetes-api/)
content/zh-cn/docs/contribute/generate-ref-docs/kubernetes-api.md
+322
View File
@@ -0,0 +1,322 @@
---
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 Kubernetes API reference documentation.
The Kubernetes API reference documentation is built from the
[Kubernetes OpenAPI spec](https://github.com/kubernetes/kubernetes/blob/master/api/openapi-spec/swagger.json)
using the [kubernetes-sigs/reference-docs](https://github.com/kubernetes-sigs/reference-docs) generation code.
If you find bugs in the generated documentation, you need to
[fix them upstream](/docs/contribute/generate-ref-docs/contribute-upstream/).
If you need only to regenerate the reference documentation from the [OpenAPI](https://github.com/OAI/OpenAPI-Specification)
spec, continue reading this page.
-->
本页面显示了如何更新 Kubernetes API 参考文档。
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) 生成代码。
如果你在生成的文档中发现错误，则需要[在上游修复](/zh/docs/contribute/generate-ref-docs/contribute-upstream/)。
如果你只需要从 [OpenAPI](https://github.com/OAI/OpenAPI-Specification) 规范中重新生成参考文档，请继续阅读此页。
## {{% heading "prerequisites" %}}
{{< include "prerequisites-ref-docs.md" >}}
<!-- steps -->
<!--
## Setting up the local repositories
Create a local workspace and set your `GOPATH`.
-->
## 配置本地仓库
创建本地工作区并设置你的 `GOPATH`。
```shell
mkdir -p $HOME/<workspace>
export GOPATH=$HOME/<workspace>
```
<!--
Get a local clone of the following repositories:
-->
获取以下仓库的本地克隆：
```shell
go get -u github.com/kubernetes-sigs/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` 仓库，现在下载：
```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：
```shell
git clone https://github.com/kubernetes/kubernetes $GOPATH/src/k8s.io/kubernetes
```
<!--
* The base directory of your clone of the
[kubernetes/kubernetes](https://github.com/kubernetes/kubernetes) repository is
`$GOPATH/src/k8s.io/kubernetes.`
The remaining steps refer to your base directory as `<k8s-base>`.
* The base directory of your clone of the
[kubernetes/website](https://github.com/kubernetes/website) repository is
`$GOPATH/src/github.com/<your username>/website.`
The remaining steps refer to your base directory as `<web-base>`.
* The base directory of your clone of the
[kubernetes-sigs/reference-docs](https://github.com/kubernetes-sigs/reference-docs)
repository is `$GOPATH/src/github.com/kubernetes-sigs/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-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
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" >}}/)。
<!--
### Setting build variables
Go to `<rdocs-base>`, and open the `Makefile` for editing:
-->
### 设置构建变量 {#setting-build-variables}
<!--
* 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.0, set `K8S_RELEASE` to 1.17.0.
-->
* 设置 `K8S_ROOT` 为 `<k8s-base>`.
* 设置 `K8S_WEBROOT` 为 `<web-base>`.
* 设置 `K8S_RELEASE` 为要构建的文档的版本。
例如，如果你想为 Kubernetes 1.17.0 构建文档，请将 `K8S_RELEASE` 设置为 1.17.0。
<!--
For example:
-->
例如：
```shell
export K8S_WEBROOT=${GOPATH}/src/github.com/<your-username>/website
export K8S_ROOT=${GOPATH}/src/k8s.io/kubernetes
export K8S_RELEASE=1.17.0
```
<!--
### Creating versioned directory and fetching Open API spec
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>`.
-->
### 创建版本目录并复制 OpenAPI 规范
构建目标 `updateapispec` 负责创建版本化的构建目录。
目录创建了之后，从 `<k8s-base>` 仓库取回 OpenAPI 规范文件。
这些步骤确保配置文件的版本和 Kubernetes OpenAPI 规范的版本与发行版本匹配。
版本化目录的名称形式为 `v<major>_<minor>`。
<!--
In the `<rdocs-base>` directory, run the following build target:
-->
在 `<rdocs-base>` 目录中，运行以下命令来构建：
```shell
cd <rdocs-base>
make updateapispec
```
<!--
### 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 参考文档
构建目标 `copyapi` 会生成 API 参考文档并将所生成文件复制到
`<web-base` 中的目录下。
在 `<rdocs-base>` 目录中运行以下命令：
```shell
cd <rdocs-base>
make copyapi
```
<!--
Verify that these two files have been generated:
-->
验证是否已生成这两个文件：
```shell
[ -e "<rdocs-base>/gen-apidocs/build/index.html" ] && echo "index.html built" || echo "no index.html"
[ -e "<rdocs-base>/gen-apidocs/build/navData.js" ] && echo "navData.js built" || echo "no navData.js"
```
<!--
Go to the base of your local `<web-base>`, and
view which files have been modified:
-->
进入本地 `<web-base>` 目录，检查哪些文件被更改：
```shell
cd <web-base>
git status
```
<!--
The output is similar to:
-->
输出类似于：
```
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/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/api-index.md`，
API 参考的版本号。例如：
```
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.
-->
* 打开编辑 `<web-base>/content/en/docs/reference/_index.md`，添加指向最新 API 参考
的链接，删除最老的 API 版本。
通常保留最近的五个版本的 API 参考的链接。
<!--
## Locally test the API reference
Publish a local version of the API reference.
Verify the [local preview](http://localhost:1313/docs/reference/generated/kubernetes-api/{{< param "version">}}/).
-->
## 在本地测试 API 参考
发布 API 参考的本地版本。
检查[本地预览](http://localhost:1313/docs/reference/generated/kubernetes-api/{{< param "version">}}/)。
```shell
cd <web-base>
git submodule update --init --recursive --depth 1 # if not already done
make container-serve
```
<!--
## Commit the changes
In `<web-base>` run `git add` and `git commit` to commit the change.
-->
## 提交更改
在 `<web-base>` 中运行 `git add` 和 `git commit` 来提交更改。
<!--
Submit your changes as a
[pull request](/docs/contribute/new-content/open-a-pr/) to the
[kubernetes/website](https://github.com/kubernetes/website) repository.
Monitor your pull request, and respond to reviewer comments as needed. Continue
to monitor your pull request until it has been merged.
-->
基于你所生成的更改[创建 PR](/zh/docs/contribute/new-content/open-a-pr/)，
提交到 [kubernetes/website](https://github.com/kubernetes/website) 仓库。
监视你提交的 PR，并根据需要回复 reviewer 的评论。继续监视你的 PR，直到合并为止。
## {{% heading "whatsnext" %}}
<!--
* [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/)
-->
* [生成参考文档快速入门](/zh/docs/contribute/generate-ref-docs/quickstart/)
* [为 Kubernetes 组件和工具生成参考文档](/zh/docs/contribute/generate-ref-docs/kubernetes-components/)
* [为 kubectl 命令集生成参考文档](/zh/docs/contribute/generate-ref-docs/kubectl/)
content/zh-cn/docs/contribute/generate-ref-docs/kubernetes-components.md
+50
View File
@@ -0,0 +1,50 @@
---
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 build the Kubernetes component and tool reference pages.
-->
本页面描述如何构造 Kubernetes 组件和工具的参考文档。
## {{% heading "prerequisites" %}}
<!--
Start with the [Prerequisites section](/docs/contribute/generate-ref-docs/quickstart/#before-you-begin)
in the Reference Documentation Quickstart guide.
-->
阅读参考文档快速入门指南中的[准备工作](/zh/docs/contribute/generate-ref-docs/quickstart/#before-you-begin)节。
<!-- steps -->
<!--
Follow the [Reference Documentation Quickstart](/docs/contribute/generate-ref-docs/quickstart/)
to generate the Kubernetes component and tool reference pages.
-->
按照[参考文档快速入门](/zh/docs/contribute/generate-ref-docs/quickstart/)
指引，生成 Kubernetes 组件和工具的参考文档。
## {{% heading "whatsnext" %}}
<!--
* [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/)
-->
* [生成参考文档快速入门](/zh/docs/contribute/generate-ref-docs/quickstart/)
* [为 kubectll 命令生成参考文档](/zh/docs/contribute/generate-ref-docs/kubectl/)
* [为 Kubernetes API 生成参考文档](/zh/docs/contribute/generate-ref-docs/kubernetes-api/)
* [为上游 Kubernetes 项目做贡献以改进文档](/zh/docs/contribute/generate-ref-docs/contribute-upstream/)
content/zh-cn/docs/contribute/generate-ref-docs/prerequisites-ref-docs.md
+45
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/new-content/open-a-pr/#fork-the-repo).
-->
- 你的 `PATH` 环境变量必须包含所需要的构建工具，例如 `Go` 程序和 `python`。
- 你需要知道如何为一个 GitHub 仓库创建拉取请求（PR）。
这牵涉到创建仓库的派生（fork）副本。
有关信息可进一步查看[基于本地副本开展工作](/zh/docs/contribute/new-content/open-a-pr/#fork-the-repo)。
content/zh-cn/docs/contribute/generate-ref-docs/quickstart.md
+405
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.py` script to generate
the Kubernetes reference documentation. The script automates
the build setup and generates the reference documentation for a release.
-->
本页讨论如何使用 `update-imported-docs.py` 脚本来生成 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` remote on
GitHub (`main` branch), and clone your `website` fork.
-->
## 获取文档仓库 {#getting-the-docs-repository}
确保你的 `website` 派生仓库与 GitHub 上的 `kubernetes/website` 远程仓库（`main` 分支）保持同步，
并克隆你的派生仓库。
```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 参考资料，可以阅读
[上游贡献指南](/zh/docs/contribute/generate-ref-docs/contribute-upstream).
{{< /note >}}
<!--
## Overview of update-imported-docs
The `update-imported-docs.py` 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.py` 位于 `<web-base>/update-imported-docs/` 目录下，
能够生成以下参考文档：
* Kubernetes 组件和工具的参考页面
* `kubectl` 命令参考文档
* Kubernetes API 参考文档
<!--
The `update-imported-docs.py` 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.py` 基于 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.py` 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.py` 执行以下步骤：
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 文档必须遵从
[文档样式指南](/zh/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.py` tool as follows:
-->
## 运行 update-imported-docs 工具
你可以用如下方式运行 `update-imported-docs.py` 工具：
```shell
cd <web-base>/update-imported-docs
./update-imported-docs.py <configuration-file.yml> <release-version>
```
<!-- For example: -->
例如：
```shell
./update-imported-docs.py 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/main/update-imported-docs/release.yml).
-->
## 修复链接
配置文件 `release.yml` 中包含用来修复相对链接的指令。
若要修复导入文件中的相对链接，将 `gen-absolute-links` 属性设置为 `true`。
你可以在 [`release.yml`](https://github.com/kubernetes/website/blob/main/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 被合并几分钟之后，你所做的对参考文档的变更就会出现
[发布的文档](/zh/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 组件和工具生成参考文档](/zh/docs/contribute/generate-ref-docs/kubernetes-components/)
* [为 kubectl 命令生成参考文档](/zh/docs/contribute/generate-ref-docs/kubectl/)
* [为 Kubernetes API 生成参考文档](/zh/docs/contribute/generate-ref-docs/kubernetes-api/)