为 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>
获取以下仓库的本地克隆：
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/<your username>/website。后续步骤将此目录称为<web-base>。 - kubernetes-sigs/reference-docs
仓库克隆后的基本目录为
$GOPATH/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=${GOPATH}/src/github.com/<your-username>/website
export K8S_ROOT=${GOPATH}/src/k8s.io/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 参考索引页面
在为新发行版本生成参考文档时，需要更新下面的文件，使之包含新的版本号：
<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 # 如果尚未完成
make container-serve
提交更改
在 <web-base> 中运行 git add 和 git commit 来提交更改。
基于你所生成的更改创建 PR， 提交到 kubernetes/website 仓库。 监视你提交的 PR，并根据需要回复 reviewer 的评论。继续监视你的 PR，直到合并为止。
接下来
Feedback
Was this page helpful?
Glad to hear it! Please tell us how we can improve.
Sorry to hear that. Please tell us how we can improve.