[zh-cn] sync generate-ref-docs/kubernetes-api contribute-upstream
Signed-off-by: xin.li <xin.li@daocloud.io>pull/44660/head
xin.li
parent
ada9a60804
commit
ae62625ab5
|
|
@ -90,7 +90,7 @@ Kubernetes API 和 `kube-*` 组件（例如 `kube-apiserver`、`kube-controller-
|
|||
当你在生成的文档中看到错误时，你可能需要考虑创建一个 PR 用来在上游项目中对其进行修复。
|
||||
|
||||
<!--
|
||||
## Cloning the Kubernetes repository
|
||||
## Clone the Kubernetes repository
|
||||
|
||||
If you don't already have the kubernetes/kubernetes repository, get it now:
|
||||
-->
|
||||
|
|
@ -108,7 +108,7 @@ 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.`
|
||||
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) 代码仓库克隆的根目录。
|
||||
|
|
@ -119,7 +119,7 @@ The remaining steps refer to your base directory as `<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.`
|
||||
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)
|
||||
|
|
@ -129,7 +129,7 @@ The remaining steps refer to your base directory as `<rdocs-base>`.
|
|||
接下来其余步骤将你的根目录称为 `<rdocs-base>`。
|
||||
|
||||
<!--
|
||||
## Editing the Kubernetes source code
|
||||
## Edit 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
|
||||
|
|
@ -149,9 +149,9 @@ you want to fix in order to fix the generated documentation.
|
|||
`kube-*` 组件的文档也是从上游源代码生成的。你必须更改与要修复的组件相关的代码，才能修复生成的文档。
|
||||
|
||||
<!--
|
||||
### Making changes to the upstream source code
|
||||
### Make changes to the upstream source code
|
||||
|
||||
The following steps are an example, not a general procedure. Details
|
||||
The following steps are an example, not a general procedure. Details
|
||||
will be different in your situation.
|
||||
-->
|
||||
### 更改上游 Kubernetes 源代码
|
||||
|
|
@ -209,7 +209,7 @@ On branch master
|
|||
```
|
||||
|
||||
<!--
|
||||
### Committing your edited file
|
||||
### Commit 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.
|
||||
|
|
@ -220,7 +220,7 @@ you will do a second commit. It is important to keep your changes separated into
|
|||
在下一步中，你将进行第二次提交，将更改分成两个提交很重要。
|
||||
|
||||
<!--
|
||||
### Generating the OpenAPI spec and related files
|
||||
### Generate the OpenAPI spec and related files
|
||||
|
||||
Go to `<k8s-base>` and run these scripts:
|
||||
-->
|
||||
|
|
@ -305,7 +305,7 @@ repository and in related repositories, such as
|
|||
{{< /note >}}
|
||||
|
||||
<!--
|
||||
### Cherry picking your commit into a release branch
|
||||
### Cherry pick 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
|
||||
|
|
@ -324,7 +324,7 @@ release-{{< skew prevMinorVersion >}} branch.
|
|||
|
||||
<!--
|
||||
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
|
||||
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).
|
||||
|
|
@ -385,7 +385,7 @@ master 分支中生成的文件可能包含不在 {{< skew prevMinorVersion >}}
|
|||
中但正在为 {{< skew latestVersion >}} 开发的 API 元素。
|
||||
|
||||
<!--
|
||||
## Generating the published reference docs
|
||||
## Generate 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
|
||||
|
|
@ -399,7 +399,9 @@ the API reference documentation.
|
|||
`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
|
||||
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" >}}/).
|
||||
-->
|
||||
现在，你可以按照
|
||||
|
|
|
|||
|
|
@ -21,19 +21,21 @@ using the [kubernetes-sigs/reference-docs](https://github.com/kubernetes-sigs/re
|
|||
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)
|
||||
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) 生成代码。
|
||||
[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-cn/docs/contribute/generate-ref-docs/contribute-upstream/)。
|
||||
|
||||
如果你只需要从 [OpenAPI](https://github.com/OAI/OpenAPI-Specification) 规范中重新生成参考文档，请继续阅读此页。
|
||||
如果你只需要从 [OpenAPI](https://github.com/OAI/OpenAPI-Specification)
|
||||
规范中重新生成参考文档，请继续阅读此页。
|
||||
|
||||
## {{% heading "prerequisites" %}}
|
||||
|
||||
|
|
@ -42,13 +44,13 @@ Kubernetes API 参考文档是从
|
|||
<!-- steps -->
|
||||
|
||||
<!--
|
||||
## Setting up the local repositories
|
||||
## Set up the local repositories
|
||||
|
||||
Create a local workspace and set your `GOPATH`.
|
||||
Create a local workspace and set your `GOPATH`:
|
||||
-->
|
||||
## 配置本地仓库
|
||||
|
||||
创建本地工作区并设置你的 `GOPATH`。
|
||||
创建本地工作区并设置你的 `GOPATH`：
|
||||
|
||||
```shell
|
||||
mkdir -p $HOME/<workspace>
|
||||
|
|
@ -87,30 +89,30 @@ 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>`.
|
||||
[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>`.
|
||||
[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-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.`。
|
||||
仓库克隆后的基本目录为 `$GOPATH/src/github.com/kubernetes-sigs/reference-docs`。
|
||||
后续步骤将此目录称为 `<rdocs-base>`。
|
||||
|
||||
<!--
|
||||
## Generating the API reference docs
|
||||
## Generate the API reference docs
|
||||
|
||||
This section shows how to generate the
|
||||
[published Kubernetes API reference documentation](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/).
|
||||
|
|
@ -120,11 +122,13 @@ This section shows how to generate the
|
|||
本节说明如何生成[已发布的 Kubernetes API 参考文档](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/)。
|
||||
|
||||
<!--
|
||||
### Setting build variables
|
||||
### Set build variables
|
||||
|
||||
Go to `<rdocs-base>`, and open the `Makefile` for editing:
|
||||
-->
|
||||
### 设置构建变量 {#setting-build-variables}
|
||||
### 设置构建变量 {#set-build-variables}
|
||||
|
||||
进入 `<rdocs-base>` 目录，然后打开 `Makefile` 文件进行编辑：
|
||||
|
||||
<!--
|
||||
* Set `K8S_ROOT` to `<k8s-base>`.
|
||||
|
|
@ -132,8 +136,8 @@ Go to `<rdocs-base>`, and open the `Makefile` for editing:
|
|||
* 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_ROOT` 为 `<k8s-base>`。
|
||||
* 设置 `K8S_WEBROOT` 为 `<web-base>`。
|
||||
* 设置 `K8S_RELEASE` 为要构建的文档的版本。
|
||||
例如，如果你想为 Kubernetes 1.17.0 构建文档，请将 `K8S_RELEASE` 设置为 1.17.0。
|
||||
|
||||
|
|
@ -149,9 +153,9 @@ export K8S_RELEASE=1.17.0
|
|||
```
|
||||
|
||||
<!--
|
||||
### Creating versioned directory and fetching Open API spec
|
||||
### Create versioned directory and fetch Open API spec
|
||||
|
||||
The `updateapispec` build target creates the versioned build directory.
|
||||
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.
|
||||
|
|
@ -167,7 +171,7 @@ The versioned directory name follows the pattern of `v<major>_<minor>`.
|
|||
<!--
|
||||
In the `<rdocs-base>` directory, run the following build target:
|
||||
-->
|
||||
在 `<rdocs-base>` 目录中，运行以下命令来构建：
|
||||
在 `<rdocs-base>` 目录中，运行以下命令来构建：
|
||||
|
||||
```shell
|
||||
cd <rdocs-base>
|
||||
|
|
@ -175,12 +179,11 @@ make updateapispec
|
|||
```
|
||||
|
||||
<!--
|
||||
### Building the API reference docs
|
||||
### Build 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 参考文档
|
||||
|
||||
|
|
@ -236,7 +239,7 @@ static/docs/reference/generated/kubernetes-api/{{< param "version" >}}/js/scroll
|
|||
```
|
||||
|
||||
<!--
|
||||
## Updating the API reference index pages
|
||||
## Update 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
|
||||
|
|
@ -251,25 +254,26 @@ version number.
|
|||
* 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/)
|
||||
```
|
||||
```
|
||||
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/)
|
||||
```
|
||||
```
|
||||
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 版本。
|
||||
* 打开编辑 `<web-base>/content/en/docs/reference/_index.md`，添加指向最新 API
|
||||
参考的链接，删除最老的 API 版本。
|
||||
通常保留最近的五个版本的 API 参考的链接。
|
||||
|
||||
<!--
|
||||
|
|
@ -283,16 +287,19 @@ Verify the [local preview](http://localhost:1313/docs/reference/generated/kubern
|
|||
发布 API 参考的本地版本。
|
||||
检查[本地预览](http://localhost:1313/docs/reference/generated/kubernetes-api/{{< param "version">}}/)。
|
||||
|
||||
<!--
|
||||
# if not already done
|
||||
-->
|
||||
```shell
|
||||
cd <web-base>
|
||||
git submodule update --init --recursive --depth 1 # if not already done
|
||||
git submodule update --init --recursive --depth 1 # 如果尚未完成
|
||||
make container-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.
|
||||
-->
|
||||
## 提交更改
|
||||
|
||||
|
|
@ -319,4 +326,3 @@ to monitor your pull request until it has been merged.
|
|||
* [生成参考文档快速入门](/zh-cn/docs/contribute/generate-ref-docs/quickstart/)
|
||||
* [为 Kubernetes 组件和工具生成参考文档](/zh-cn/docs/contribute/generate-ref-docs/kubernetes-components/)
|
||||
* [为 kubectl 命令集生成参考文档](/zh-cn/docs/contribute/generate-ref-docs/kubectl/)
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue