为 Kubernetes API 生成参考文档
本页面显示了如何更新 Kubernetes API 参考文档。
Kubernetes API 参考文档是从 Kubernetes OpenAPI 规范构建的， 且使用 kubernetes-sigs/reference-docs 生成代码。
如果你在生成的文档中发现错误，则需要在上游修复。
如果你只需要从 OpenAPI 规范中重新生成参考文档，请继续阅读此页。
准备开始
需求
你需要一台 Linux 或 macOS 机器。
你需要安装以下工具：
你的
PATH环境变量必须包含所需要的构建工具，例如Go程序和python。你需要知道如何为一个 GitHub 仓库创建拉取请求（PR）。 这牵涉到创建仓库的派生（fork）副本。 有关信息可进一步查看基于本地副本开展工作。
配置本地仓库
创建本地工作区并设置你的 GOPATH：
mkdir -p $HOME/<workspace>
export GOPATH=$HOME/<workspace>
获取以下仓库的本地克隆：
git clone github.com/kubernetes-sigs/reference-docs
将其移动到 reference-docs 仓库的 gen-apidocs 目录中，
并安装所需的 Go 包：
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
克隆 kubernetes/kubernetes 仓库：
git clone https://github.com/kubernetes/kubernetes
kubernetes/kubernetes 仓库克隆后的根目录为
<your-path-to>/src/k8s.io/kubernetes。 后续步骤将此目录称为<k8s-base>。kubernetes/website 仓库克隆后的根目录为
<your-path-to>/src/github.com/<your username>/website。后续步骤将此目录称为<web-base>。kubernetes-sigs/reference-docs 仓库克隆后的基本目录为
<your-path-to>/src/github.com/kubernetes-sigs/reference-docs。 后续步骤将此目录称为<rdocs-base>。
生成 API 参考文档
本节说明如何生成已发布的 Kubernetes API 参考文档。
设置构建变量
进入 <rdocs-base> 目录，然后打开 Makefile 文件进行编辑：
- 设置
K8S_ROOT为<k8s-base>。 - 设置
K8S_WEBROOT为<web-base>。 - 设置
K8S_RELEASE为要构建的文档的版本。 例如，如果你想为 Kubernetes 1.17.0 构建文档，请将K8S_RELEASE设置为 1.17.0。
例如：
export K8S_WEBROOT=<your-path-to>/website
export K8S_ROOT=<your-path-to>/kubernetes
export K8S_RELEASE=1.17.0
创建版本目录并复制 OpenAPI 规范
构建目标 updateapispec 负责创建版本化的构建目录。
目录创建了之后，从 <k8s-base> 仓库取回 OpenAPI 规范文件。
这些步骤确保配置文件的版本和 Kubernetes OpenAPI 规范的版本与发行版本匹配。
版本化目录的名称形式为 v<major>_<minor>。
在 <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.34/css/bootstrap.min.css
static/docs/reference/generated/kubernetes-api/v1.34/css/font-awesome.min.css
static/docs/reference/generated/kubernetes-api/v1.34/css/stylesheet.css
static/docs/reference/generated/kubernetes-api/v1.34/fonts/FontAwesome.otf
static/docs/reference/generated/kubernetes-api/v1.34/fonts/fontawesome-webfont.eot
static/docs/reference/generated/kubernetes-api/v1.34/fonts/fontawesome-webfont.svg
static/docs/reference/generated/kubernetes-api/v1.34/fonts/fontawesome-webfont.ttf
static/docs/reference/generated/kubernetes-api/v1.34/fonts/fontawesome-webfont.woff
static/docs/reference/generated/kubernetes-api/v1.34/fonts/fontawesome-webfont.woff2
static/docs/reference/generated/kubernetes-api/v1.34/index.html
static/docs/reference/generated/kubernetes-api/v1.34/js/jquery.scrollTo.min.js
static/docs/reference/generated/kubernetes-api/v1.34/js/navData.js
static/docs/reference/generated/kubernetes-api/v1.34/js/scroll.js
API 参考位置和版本控制
生成的 API 参考文件（HTML 版本）被复制到
<web-base>/static/docs/reference/generated/kubernetes-api/v1.34/。
此目录包含了独立的 HTML API 文档。
说明：
API 参考的 Markdown 版本位于 <web-base>/content/en/docs/reference/kubernetes-api/，
是使用 gen-resourcesdocs
生成器单独生成的。
在本地测试 API 参考
发布 API 参考的本地版本。 检查本地预览。
cd <web-base>
git submodule update --init --recursive --depth 1 # 如果尚未完成
make container-serve
提交更改
在 <web-base> 中运行 git add 和 git commit 来提交更改。
基于你所生成的更改创建 PR， 提交到 kubernetes/website 仓库。 监视你提交的 PR，并根据需要回复 reviewer 的评论。继续监视你的 PR，直到合并为止。