From acbb74139f62de100a5391c67467baf92aeb2ef3 Mon Sep 17 00:00:00 2001
From: Li Yuan <li.yuan4@zte.com.cn>
Date: Mon, 24 Dec 2018 21:15:50 +0800
Subject: [PATCH] zh-trans: /docs/contribute/style/kubernetes-components.md
 (#11838)

Signed-off-by: liyuan198251 <li.yuan4@zte.com.cn>

zh-trans: /docs/contribute/generate-ref-docs/kubernetes-components.md; update

Signed-off-by: liyuan198251 <li.yuan4@zte.com.cn>
---
 .../kubernetes-components.md                  | 412 ++++++++++++++++++
 1 file changed, 412 insertions(+)
 create mode 100644 content/zh/docs/contribute/generate-ref-docs/kubernetes-components.md

diff --git a/content/zh/docs/contribute/generate-ref-docs/kubernetes-components.md b/content/zh/docs/contribute/generate-ref-docs/kubernetes-components.md
new file mode 100644
index 0000000000..9653d0a04e
--- /dev/null
+++ b/content/zh/docs/contribute/generate-ref-docs/kubernetes-components.md
@@ -0,0 +1,412 @@
+---
+title: 为 Kubernetes 组件和工具生成参考页面
+content_template: templates/task
+---
+
+<!--
+---
+title: Generating Reference Pages for Kubernetes Components and Tools
+content_template: templates/task
+---
+-->
+
+{{% capture 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.
+-->
+
+本页面展示了如何使用 `update-imported-docs` 工具来为 [Kubernetes](https://github.com/kubernetes/kubernetes) 和 [Federation](https://github.com/kubernetes/federation) 仓库中的工具和组件生成参考文档。
+
+{{% /capture %}}
+
+{{% capture prerequisites %}}
+
+<!--
+* You need a machine that is running Linux or macOS.
+-->
+
+* 您需要一个运行着 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/)。
+
+{{% /capture %}}
+
+{{% capture steps %}}
+
+<!--
+## Getting two repositories
+-->
+
+## 下载两个仓库
+
+<!--
+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](https://kubernetes.io/docs/home/contribute/create-pull-request/)
+to `kubernetes/website`.
+-->
+
+当 Markdown 文件放入 `kubernetes/website` 仓库的本地目录中后，你就可以创建 [PR](https://kubernetes.io/docs/home/contribute/create-pull-request/) 将它们提交到 `kubernetes/website`。
+
+<!--
+## Customizing the config file
+-->
+
+## 自定义配置文件
+
+<!--
+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` 条目的内容，除非你了解它的作用，并且需要修改指定的已发布分支。
+
+```shell
+repos:
+- name: reference-docs
+  remote: https://github.com/kubernetes-incubator/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.11
+    make generated_files
+    cp -L -R vendor $GOPATH/src
+    rm -r vendor
+    cd $GOPATH
+    go get -v github.com/kubernetes-incubator/reference-docs/gen-compdocs
+    cd src/github.com/kubernetes-incubator/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/)中。
+
+{{% /capture %}}
+
+{{% capture 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/)
+-->
+
+* [为 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/)
+
+{{% /capture %}}
\ No newline at end of file