生成 Kubernetes API 的参考文档

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

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

如果您发现生成的文档中存在错误,您需要 在 upstream 进行修复

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

准备工作

要求

  • 您需要一台运行 Linux 或 macOS 的机器。

  • 您需要安装以下工具

  • 您的 PATH 环境变量必须包含必需的构建工具,例如 Go 二进制文件和 python

  • 您需要了解如何向 GitHub 存储库创建拉取请求。这包括创建存储库的个人分支。有关更多信息,请参阅 从本地克隆进行工作

设置本地仓库

创建本地工作区并设置您的 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 参考文档

设置构建变量

  • 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 构建目标会创建版本化的构建目录。目录创建后,Open API 规范将从 <k8s-base> 仓库获取。这些步骤可确保配置文件和 Kubernetes Open API 规范的版本与发布版本匹配。版本化目录的名称遵循 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 # if not already done
make container-serve

提交更改

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

将您的更改作为 Pull Request 提交到 kubernetes/website 仓库。监控您的 Pull Request,并根据需要响应审阅者的评论。继续监控您的 Pull Request,直到它被合并。

下一步

最后修改于 2024 年 1 月 2 日下午 8:14 PST:清理三个 generate-ref-docs (4d6a8e57c0)