为 Kubernetes API 生成参考文档
本页面介绍如何更新 Kubernetes API 参考文档。
Kubernetes API 参考文档是使用 kubernetes-sigs/reference-docs 生成代码，基于 Kubernetes OpenAPI spec 构建的。
如果你在生成的文档中发现错误，你需要在上游进行修复。
如果你只需从 OpenAPI 规约重新生成参考文档，请继续阅读本页面。
开始之前
要求
你需要一台运行 Linux 或 macOS 的机器。
你需要安装以下工具：
你的
PATH环境变量必须包含所需的构建工具，例如Go可执行文件和python。你需要知道如何向 GitHub 仓库创建拉取请求（Pull Request）。这包括创建你自己的仓库分支（fork）。更多信息，请参考从本地克隆版本工作。
设置本地仓库
创建本地工作空间并设置你的 GOPATH
mkdir -p $HOME/<workspace>
export GOPATH=$HOME/<workspace>
克隆以下仓库到本地
go get -u github.com/kubernetes-sigs/reference-docs
go get -u github.com/go-openapi/loads
go get -u github.com/go-openapi/spec
如果你还没有 kubernetes/website 仓库，现在就获取它
git clone https://github.com/<your-username>/website $GOPATH/src/github.com/<your-username>/website
将 kubernetes/kubernetes 仓库克隆为 k8s.io/kubernetes
git clone https://github.com/kubernetes/kubernetes $GOPATH/src/k8s.io/kubernetes
你克隆的 kubernetes/kubernetes 仓库的基本目录是
$GOPATH/src/k8s.io/kubernetes。接下来的步骤将你的基本目录称为<k8s-base>。你克隆的 kubernetes/website 仓库的基本目录是
$GOPATH/src/github.com/<你的用户名>/website。接下来的步骤将你的基本目录称为<web-base>。你克隆的 kubernetes-sigs/reference-docs 仓库的基本目录是
$GOPATH/src/github.com/kubernetes-sigs/reference-docs。接下来的步骤将你的基本目录称为<rdocs-base>。
生成 API 参考文档
本节展示如何生成已发布的 Kubernetes API 参考文档。
设置构建变量
- 将
K8S_ROOT设置为<k8s-base>。 - 将
K8S_WEBROOT设置为<web-base>。 - 将
K8S_RELEASE设置为你想要构建的文档版本。例如，如果你想构建 Kubernetes 1.17.0 的文档，将K8S_RELEASE设置为 1.17.0。
例如
export K8S_WEBROOT=${GOPATH}/src/github.com/<your-username>/website
export K8S_ROOT=${GOPATH}/src/k8s.io/kubernetes
export K8S_RELEASE=1.17.0
创建版本化目录并获取 Open API 规约
updateapispec 构建目标会创建版本化的构建目录。目录创建后，将从 <k8s-base> 仓库获取 Open API 规约。这些步骤确保配置文件和 Kubernetes Open API 规约的版本与发布版本匹配。版本化目录的名称遵循 v<主版本号>_<次版本号> 的模式。
在 <rdocs-base> 目录下，运行以下构建目标：
cd <rdocs-base>
make updateapispec
构建 API 参考文档
copyapi 目标会构建 API 参考文档并将生成的文件复制到 <web-base> 中的目录。在 <rdocs-base> 中运行以下命令：
cd <rdocs-base>
make copyapi
验证以下两个文件是否已生成
[ -e "<rdocs-base>/gen-apidocs/build/index.html" ] && echo "index.html built" || echo "no index.html"
[ -e "<rdocs-base>/gen-apidocs/build/navData.js" ] && echo "navData.js built" || echo "no navData.js"
进入你的本地 <web-base> 目录，查看哪些文件已被修改：
cd <web-base>
git status
输出类似：
static/docs/reference/generated/kubernetes-api/v1.33/css/bootstrap.min.css
static/docs/reference/generated/kubernetes-api/v1.33/css/font-awesome.min.css
static/docs/reference/generated/kubernetes-api/v1.33/css/stylesheet.css
static/docs/reference/generated/kubernetes-api/v1.33/fonts/FontAwesome.otf
static/docs/reference/generated/kubernetes-api/v1.33/fonts/fontawesome-webfont.eot
static/docs/reference/generated/kubernetes-api/v1.33/fonts/fontawesome-webfont.svg
static/docs/reference/generated/kubernetes-api/v1.33/fonts/fontawesome-webfont.ttf
static/docs/reference/generated/kubernetes-api/v1.33/fonts/fontawesome-webfont.woff
static/docs/reference/generated/kubernetes-api/v1.33/fonts/fontawesome-webfont.woff2
static/docs/reference/generated/kubernetes-api/v1.33/index.html
static/docs/reference/generated/kubernetes-api/v1.33/js/jquery.scrollTo.min.js
static/docs/reference/generated/kubernetes-api/v1.33/js/navData.js
static/docs/reference/generated/kubernetes-api/v1.33/js/scroll.js
更新 API 参考索引页面
为新发布版本生成参考文档时，使用新的版本号更新文件 <web-base>/content/en/docs/reference/kubernetes-api/api-index.md。
打开
<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/)打开
<web-base>/content/en/docs/reference/_index.md进行编辑，并为最新的 API 参考添加新链接。移除最旧的 API 参考版本。应该保留指向最近五个 API 参考的链接。
本地测试 API 参考文档
发布本地版本的 API 参考文档。验证本地预览。
cd <web-base>
git submodule update --init --recursive --depth 1 # if not already done
make container-serve
提交更改
在 <web-base> 目录中，运行 git add 和 git commit 提交更改。
将你的更改作为拉取请求（Pull Request）提交到 kubernetes/website 仓库。关注你的拉取请求，并根据需要回复评审者的评论。继续关注你的拉取请求，直到它被合并。