为 Kubernetes API 生成参考文档

本页面显示了如何更新 Kubernetes API 参考文档。

Kubernetes API 参考文档是从 Kubernetes OpenAPI 规范 构建的, 且使用kubernetes-sigs/reference-docs 生成代码。

如果您在生成的文档中发现错误,则需要在上游修复

如果您只需要从 OpenAPI 规范中重新生成参考文档,请继续阅读此页。

Before you begin

需求

  • 你需要一台 Linux 或 macOS 机器。

  • 你需要安装以下工具:

  • 你的 PATH 环境变量必须包含所需要的构建工具,例如 Go 程序和 python

  • 你需要知道如何为一个 GitHub 仓库创建拉取请求(PR)。 这牵涉到创建仓库的派生(fork)副本。 有关信息可进一步查看基于本地副本开展工作

配置本地仓库

创建本地工作区并设置你的 GOPATH

  1. mkdir -p $HOME/<workspace>
  2. export GOPATH=$HOME/<workspace>

获取以下仓库的本地克隆:

  1. go get -u github.com/kubernetes-sigs/reference-docs
  2. go get -u github.com/go-openapi/loads
  3. go get -u github.com/go-openapi/spec

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

  1. git clone https://github.com/<your-username>/website $GOPATH/src/github.com/<your-username>/website

克隆 kubernetes/kubernetes 仓库作为 k8s.io/kubernetes:

  1. 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 参考文档

设置构建变量

  • 设置 K8S_ROOT<k8s-base>.
  • 设置 K8S_WEBROOT<web-base>.
  • 设置 K8S_RELEASE 为要构建的文档的版本。 例如,如果您想为 Kubernetes 1.17.0 构建文档,请将 K8S_RELEASE 设置为 1.17.0。

例如:

  1. export K8S_WEBROOT=${GOPATH}/src/github.com/<your-username>/website
  2. export K8S_ROOT=${GOPATH}/src/k8s.io/kubernetes
  3. export K8S_RELEASE=1.17.0

创建版本目录并复制 OpenAPI 规范

构建目标 updateapispec 负责创建版本化的构建目录。 目录创建了之后,从 <k8s-base> 仓库取回 OpenAPI 规范文件。 这些步骤确保配置文件的版本和 Kubernetes OpenAPI 规范的版本与发行版本匹配。 版本化目录的名称形式为 v<major>_<minor>

<rdocs-base> 目录中,运行以下命令来构建:

  1. cd <rdocs-base>
  2. make updateapispec

构建 API 参考文档

构建目标 copyapi 会生成 API 参考文档并将所生成文件复制到 <web-base 中的目录下。 在 <rdocs-base> 目录中运行以下命令:

  1. cd <rdocs-base>
  2. make copyapi

验证是否已生成这两个文件:

  1. [ -e "<rdocs-base>/gen-apidocs/build/index.html" ] && echo "index.html built" || echo "no index.html"
  2. [ -e "<rdocs-base>/gen-apidocs/build/navData.js" ] && echo "navData.js built" || echo "no navData.js"

进入本地 <web-base> 目录,检查哪些文件被更改:

  1. cd <web-base>
  2. git status

输出类似于:

  1. static/docs/reference/generated/kubernetes-api/v1.23/css/bootstrap.min.css
  2. static/docs/reference/generated/kubernetes-api/v1.23/css/font-awesome.min.css
  3. static/docs/reference/generated/kubernetes-api/v1.23/css/stylesheet.css
  4. static/docs/reference/generated/kubernetes-api/v1.23/fonts/FontAwesome.otf
  5. static/docs/reference/generated/kubernetes-api/v1.23/fonts/fontawesome-webfont.eot
  6. static/docs/reference/generated/kubernetes-api/v1.23/fonts/fontawesome-webfont.svg
  7. static/docs/reference/generated/kubernetes-api/v1.23/fonts/fontawesome-webfont.ttf
  8. static/docs/reference/generated/kubernetes-api/v1.23/fonts/fontawesome-webfont.woff
  9. static/docs/reference/generated/kubernetes-api/v1.23/fonts/fontawesome-webfont.woff2
  10. static/docs/reference/generated/kubernetes-api/v1.23/index.html
  11. static/docs/reference/generated/kubernetes-api/v1.23/js/jquery.scrollTo.min.js
  12. static/docs/reference/generated/kubernetes-api/v1.23/js/navData.js
  13. static/docs/reference/generated/kubernetes-api/v1.23/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 参考的版本号。例如:

    1. title: v1.17
    2. [Kubernetes API v1.17](/docs/reference/generated/kubernetes-api/v1.17/)
  • 打开编辑 <web-base>/content/en/docs/reference/_index.md,添加指向最新 API 参考 的链接,删除最老的 API 版本。 通常保留最近的五个版本的 API 参考的链接。

在本地测试 API 参考

发布 API 参考的本地版本。 检查本地预览

  1. cd <web-base>
  2. git submodule update --init --recursive --depth 1 # if not already done
  3. make container-serve

提交更改

<web-base> 中运行 git addgit commit 来提交更改。

基于你所生成的更改创建 PR, 提交到 kubernetes/website 仓库。 监视您提交的 PR,并根据需要回复 reviewer 的评论。继续监视您的 PR,直到合并为止。

What’s next

最后修改 July 13, 2021 at 1:13 AM PST: [zh] Fixed variable substitution (2616547b9)