为 Kubernetes 文档做贡献

Edit This Page

为 Kubernetes API 生成参考文档

本页面展示了如何为 Kubernetes API 更新自动生成的参考文档。

准备开始

你需要安装以下软件:

在环境变量中设置 $GOPATH,并且 etcd 的路径必须配置在 $PATH 环境变量中。

你需要知道如何在一个 GitHub 项目仓库中创建一个 PR。一般来说,这涉及到创建仓库的一个分支。想了解更多信息,请参见创建一个文档 PRGitHub 标准 Fork&PR 工作流

概述

更新 Kubernetes API 参考文档有两个步骤:

  1. 从 kubernetes 源码生成 OpenAPI 规范。本步骤的工具在 kubernetes/kubernetes/hack
  1. 从 OpenAPI 规范生成 HTML 文件。本步骤的工具在 kubernetes-incubator/reference-docs

下载三个仓库

If you don’t already have the kubernetes/kubernetes repository, get it now:

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

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

如果你还没有下载过 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-incubator/reference-docs 仓库,现在下载:

mkdir $GOPATH/src
cd $GOPATH/src
go get github.com/kubernetes-incubator/reference-docs

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

编辑 Kubernetes 源码

Kubernetes API 参考文档是基于 OpenAPI 规范自动生成的,而该规范是从 Kubernetes 源码生成的。如果想要修改参考文档,可以从修改 Kubernetes 源码中的一个或多个注释开始。

修改源码中的注释

Note:

以下步骤是一个示例,而不是通用步骤。在你操作过程中,细节会有所不同。

下面是在 Kubernetes 源码中编辑注释的示例。

进入 kubernetes/kubernetes 仓库的本地目录,检出 master 分支,并确保它是最新的:

cd <k8s-base>
git checkout master
git pull https://github.com/kubernetes/kubernetes master

假设 master 分支中的这个源文件有一个拼写错误 “atmost”:

kubernetes/kubernetes/staging/src/k8s.io/api/apps/v1/types.go

在本地环境中,打开 types.go 文件,然后将 “atmost” 修改为 “at most”。

确认文件已修改:

git status

输出展示了在 master 分支上,types.go 文件已被修改:

On branch master
...
    modified:   staging/src/k8s.io/api/apps/v1/types.go

提交已编辑的文件

运行 git addgit commit 提交到目前为止所做的修改。在下一步中,你将进行第二次提交。将修改拆分为两个提交是很重要的。

生成 OpenAPI 规范和相关文件

进入 <k8s-base> 目录运行以下脚本:

hack/update-generated-swagger-docs.sh
hack/update-swagger-spec.sh
hack/update-openapi-spec.sh
hack/update-generated-protobuf.sh
hack/update-api-reference-docs.sh

运行 git status 查看生成的文件。

On branch master
...
    modified:   api/openapi-spec/swagger.json
    modified:   api/swagger-spec/apps_v1.json
    modified:   docs/api-reference/apps/v1/definitions.html
    modified:   staging/src/k8s.io/api/apps/v1/generated.proto
    modified:   staging/src/k8s.io/api/apps/v1/types.go
    modified:   staging/src/k8s.io/api/apps/v1/types_swagger_doc_generated.go

检查 api/openapi-spec/swagger.json 的内容确认拼写错误是否被修复。例如,你可以运行 git diff -a api/openapi-spec/swagger.json。这个步骤很重要,因为 swagger.json 是文档生成过程的第二个步骤的输入。

运行 git addgit commit 提交修改。现在你有两个提交:一个是已编辑的 types.go 文件,另一个是已生成的 OpenAPI 规范和相关文件。把这两个提交分开。也就是说,不要将它们合并提交。

将你的修改以 pull request 提交到 kubernetes/kubernetes 仓库的 master 分支。跟踪你的 PR,并根据需要回应评审人的评论。继续跟踪你的 PR,直到它被合入。

PR 57758 是一个对 Kubernetes 源码中的拼写错误进行修复的 PR 示例。

Note:

定位要修改的具体源文件可能很困难。在前面的示例中,正确的源文件位于 kubernetes/kubernetes 仓库的 staging 目录下。但在你的情况下,staging 目录可能不是查找正确源的位置。有关指导,请查看 kubernetes/kubernetes 仓库的 README 文件和相关仓库 kubernetes/apiserver

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

在上文中,你在 master 分支中编辑了一个文件,然后运行脚本来生成 OpenAPI 规范和相关文件。然后你在一个 PR 中向 kubernetes/kubernetes 仓库的 master 分支提交了修改。现在假设你想要将你的修改合入到一个发布分支中。例如,假设 master 分支用于开发 Kubernetes 1.10 版本,而你希望将你的修改合入到 release-1.9 分支中。

回想一下 PR 中有两个提交:一个用于编辑 types.go,另一个用于脚本生成的文件。下一步是对你在 release-1.9 分支的第一次提交提议一个 cherry-pick 合入。其目的是挑出对 types.go 的编辑的那次提交,而不是对运行脚本结果的提交。有关说明,请参见提议一个 cherry-pick 合入

Note:

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

当你有一个对 release-1.9 分支进行 cherry-pick 合入的 PR 时,下一步是在 release-1.9 分支的本地环境中运行这些脚本。

hack/update-generated-swagger-docs.sh
hack/update-swagger-spec.sh
hack/update-openapi-spec.sh
hack/update-generated-protobuf.sh
hack/update-api-reference-docs.sh

现在向 cherry pick 的 PR 添加一个提交,该 PR 包含最近生成的 OpenAPI 规范和相关文件。跟踪你的 PR,直到它合入到 release-1.9 分支中。

此时,master 和 release-1.9 分支都更新了 types.go 文件和一组生成的文件,这些反映了你对 types.go 做的修改。注意,在 release-1.9 分支中生成的 OpenAPI 规范和其他文件不一定与在 master 分支中生成的文件相同。在 release-1.9 分支中生成的文件只包含 Kubernetes 1.9 版本的 API 元素。master 分支中生成的文件可能包含正在 1.10 版本中开发的 API 元素,而这些元素却不在 1.9 版本中。

生成已发布的参考文档

前一章节展示了如何编辑源文件,然后生成几个文件,包括 kubernetes/kubernetes 仓库中的 api/openapi-spec/swagger.json

本章节介绍如何生成已发布的 Kubernetes API 参考文档,该文档由 kubernetes-incubator/reference-docs 中的工具生成。这些工具以 api/openapi-spec/swagger.json 文件作为输入。

在 kubernetes-incubator/reference-docs 仓库中编辑 Makefile 文件

进入 <rdocs-base> 目录, 打开 Makefile 进行编辑:

K8SROOT 设置为 kubernetes/kubernetes 仓库的本地主目录。将 WEBROOT 设置为 kubernetes/website 仓库的本地主目录。将 MINOR_VERSION 设置为要构建的文档的副版本号。例如,如果要为 Kubernetes 1.9 版本构建文档,请将 MINOR_VERSION 设置为 9。保存并关闭 Makefile

复制 OpenAPI 规范

文档生成代码需要 Kubernetes API 的 OpenAPI 规范的本地副本。进入 <k8s-base> 目录,检出有你想要使用的 OpenAPI 规范的分支。例如,如果要为 Kubernetes 1.9 版本生成文档,请检出 release-1.9 分支。

返回 <rdocs-base> 目录。输入以下命令将 OpenAPI 规范从 kubernetes/kubernetes 仓库复制到本地目录:

make updateapispec

输出显示文件已被复制:

cp ~/src/github.com/kubernetes/kubernetes/api/openapi-spec/swagger.json gen-apidocs/generators/openapi-spec/swagger.json

制作 brodocs 镜像

文档生成代码需要 pwittrock/brodocs Docker 镜像。

该命令用于创建 pwittrock/brodocs Docker 镜像。它还尝试将镜像推送到 DockerHub,但是如果该步骤失败也没关系。只要镜像在本地,就可以成功生成代码。

make brodocs

确认 brodocs 镜像是否存在:

docker images

输出显示 pwittrock/brodocs 是可用镜像之一:

REPOSITORY          TAG                 IMAGE ID            CREATED             SIZE
pwittrock/brodocs   latest              999d34a50d56        5 weeks ago         714MB

运行文档生成代码

构建并运行文档生成代码。你可能需要以 root 用户运行命令:

cd <rdocs-base>
make api

找到生成的文件

这两个文件是成功构建的产物。验证它们是否存在:

将生成的文档复制到 kubernetes/website 仓库

前面的章节展示了如何编辑 Kubernetes 源文件,生成 OpenAPI 规范,然后生成用于发布的参考文档。

本章节介绍如何将生成的文档复制到 kubernetes/website 仓库。kubernetes/website 仓库中的文件发布在 kubernetes.io 网站上。特别是,生成的 index.html 文件发布在这里

输入以下命令将生成的文件复制到 kubernetes/website 仓库的本地目录:

make copyapi

进入 kubernetes/kubernetes 仓库的本地主目录,查看哪些文件已被修改:

cd <web-base>
git status

输出显示修改后的文件:

On branch master
...
   modified:   docs/reference/generated/kubernetes-api/v1.9/index.html

在本例中,只修改了一个文件。回想一下,你生成了 index.htmlnavData.js。但显然生成的 navata.js 与 kubernetes/website仓库中已有的navData.js` 没有什么不同。

<web base> 目录下运行 git addgit commit 将提交修改。

将你的修改作为 pull request 提交到 kubernetes/website 仓库。跟踪你的 PR,并根据需要回应评审人的评论。继续跟踪你的 PR,直到它被合入。

在 PR 合入的几分钟后,你的修改将出现在已发布的参考文档

接下来

反馈