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

[zh] Sync contribution guidelines (2)

Browse Source 
This PR is about the changes to reference generation.
This commit is contained in:
Qiming Teng
2020-06-23 10:46:27 +08:00
parent 33f6fd9aa4
commit e8aa064289
7 changed files with 845 additions and 872 deletions
Download Patch File Download Diff File Expand all files Collapse all files
content/zh/docs/contribute/generate-ref-docs/kubernetes-api.md
+122 -185
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/)