Edit This Page

为 Kubernetes 组件和工具生成参考页面

本页面展示了如何使用 update-imported-docs 工具来为 Kubernetes 和 Federation 仓库中的工具和组件生成参考文档。

准备开始

  • 你需要一个运行着 Linux 或 macOS 操作系统的机器。
  • 在环境变量中设置 $GOPATH。
  • 你需要知道如何在一个 GitHub 项目仓库中创建一个 PR。一般来说，这涉及到创建仓库的一个分支。想了解更多信息，请参见创建一个文档 PR。

下载两个仓库

如果你还没有下载过 kubernetes/website 仓库，现在下载：

mkdir $GOPATH/src
cd $GOPATH/src
go get github.com/kubernetes/website

确定 kubernetes/website 仓库的本地主目录。例如，如果按照前面的步骤来获取该仓库，则主目录是 $GOPATH/src/github.com/kubernetes/website。下文将该目录称为 <web-base>。

如果你想对参考文档进行修改，但是你还没下载过 kubernetes/kubernetes 仓库，现在下载：

mkdir $GOPATH/src
cd $GOPATH/src
go get github.com/kubernetes/kubernetes

确定 kubernetes/kubernetes 仓库的本地主目录。例如，如果按照前面的步骤来获取该仓库，则主目录是 $GOPATH/src/github.com/kubernetes/kubernetes。下文将该目录称为 <k8s-base>。

注意： 如果你只想生成参考文档，而不需要修改，则不需要手动下载 `kubernetes/kubernetes` 仓库。当你运行 `update-imported-docs` 工具时，它会自动克隆 `kubernetes/kubernetes` 仓库。

编辑 Kubernetes 源码

Kubernetes 组件和工具的参考文档是基于 Kubernetes 源码自动生成的。如果想要修改参考文档，可以从修改 Kubernetes 源码中的一个或多个注释开始。在本地 kubernetes/kubernetes 仓库中进行修改，然后向 github.com/kubernetes/kubernetes 的 master 分支提交 PR。

PR 56942 是一个对 Kubernetes 源码中的注释进行修改的 PR 示例。

跟踪你的 PR，并回应评审人的评论。继续跟踪你的 PR，直到它合入到 kubernetes/kubernetes 仓库的 master 分支中。

以 cherry-pick 方式将你的修改合入已发布分支

你的修改已合入 master 分支中，该分支用于开发下一个 Kubernetes 版本。如果你希望修改部分出现在已发布的 Kubernetes 版本文档中，则需要提议将它们以 cherry-pick 方式合入已发布分支。

例如，假设 master 分支正用于开发 Kubernetes 1.10 版本，而你希望将修改合入到已发布的 1.9 版本分支。相关的操作指南，请参见 提议一个 cherry-pick 合入。

跟踪你的 cherry-pick PR，直到它合入到已发布分支中。

注意： 提议一个 cherry-pick 合入，需要你有在 PR 中设置标签和里程碑的权限。如果你没有，你需要与有权限为你设置标签和里程碑的人合作完成。

update-imported-docs 概述

update-imported-docs 工具在 kubernetes/website/update-imported-docs/ 目录下。它执行以下步骤：

  1. 克隆配置文件中指定的相关仓库。为了生成参考文档，默认情况下克隆的仓库是 kubernetes-incubator/reference-docs 和 kubernetes/federation。
  2. 在克隆出的仓库下运行命令来准备文档生成器，然后生成 Markdown 文件。
  3. 将生成的 Markdown 文件复制到配置文件中指定的 kubernetes/website 仓库的本地目录中。

当 Markdown 文件放入 kubernetes/website 仓库的本地目录中后，你就可以创建 PR 将它们提交到 kubernetes/website。

自定义 reference.yml 配置文件

打开 <web-base>/update-imported-docs/reference.yml 进行编辑。不要修改 generate-command 条目的内容，除非你了解它的作用，并且需要修改指定的已发布分支。

repos:
- name: reference-docs
  remote: https://github.com/kubernetes-sigs/reference-docs.git
  # This and the generate-command below needs a change when reference-docs has
  # branches properly defined
  branch: master
  generate-command: |
    cd $GOPATH
    git clone https://github.com/kubernetes/kubernetes.git src/k8s.io/kubernetes
    cd src/k8s.io/kubernetes
    git checkout release-1.17
    make generated_files
    cp -L -R vendor $GOPATH/src
    rm -r vendor
    cd $GOPATH
    go get -v github.com/kubernetes-sigs/reference-docs/gen-compdocs
    cd src/github.com/kubernetes-sigs/reference-docs/
    make comp

在 reference.yml 中，files 字段是 src 和 dst 字段的列表。src 字段指定生成的 Markdown 文件的位置，而 dst 字段指定将此文件复制到 kubernetes/website 仓库的本地目录的哪个位置。例如：

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
  ...

注意，当有许多文件要从同一个源目录复制到同一个目标目录时，可以使用通配符给 src 赋值，而使用目录名给 dst 赋值。例如：

  files:
  - src: gen-compdocs/build/kubeadm*.md
    dst: content/en/docs/reference/setup-tools/kubeadm/generated/

运行 update-imported-docs 工具

在检查与或自定义 reference.yaml 文件后，运行 update-imported-docs 工具：

cd <web-base>/update-imported-docs
./update-imported-docs reference.yml

在 kubernetes/website 中添加和提交修改

列出生成并准备合入到 kubernetes/website 仓库中的文件：

cd <web-base>
git status

输出展示了新增和修改的文件。例如，输出可能如下所示：

...

    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
...

运行 git add 和 git commit 将提交上述文件。

创建 PR

对 kubernetes/website 仓库创建 PR。跟踪你的 PR，并根据需要回应评审人的评论。继续跟踪你的 PR，直到它被合入。

在 PR 合入的几分钟后，你更新的参考主题将出现在已发布文档中。

接下来