Edit This Page

为 Kubernetes API 生成参考文档

本页面展示了如何为 Kubernetes API 更新自动生成的参考文档。 Kubernetes API 参考文档是从 Kubernetes OpenAPI 规范构建的,而工具是从 kubernetes-incubator/reference-docs 构建的。

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

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

准备开始

你需要安装以下软件:

你需要知道如何在一个 GitHub 项目仓库中创建一个 PR。一般来说,这涉及到创建仓库的 fork 分支。想了解更多信息,请参见创建一个文档 PRGitHub 标准 Fork & PR 工作流

设置本地仓库

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

mkdir -p $HOME/<workspace>

export GOPATH=$HOME/<workspace>

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

go get -u github.com/kubernetes-incubator/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-incubator/reference-docs 仓库克隆后的基本目录为 $GOPATH/src/github.com/kubernetes-incubator/reference-docs。 其余后续步骤将您的基本目录称为 <rdocs-base>

生成 API 参考文档

本节说明如何生成已发布的 Kubernetes API 参考文档

修改 Makefile 文件

进入 <rdocs-base> 目录,然后编辑 Makefile 文件:

  • 设置 K8SROOT<k8s-base>.
  • 设置 WEBROOT<web-base>.
  • 设置 MINOR_VERSION 为要构建的文档的次要版本。例如,如果您想为 Kubernetes 1.15 构建文档,请将 MINOR_VERSION 设置为 15。保存并关闭 Makefile 文件。

例如,更新以下变量:

WEBROOT=$(GOPATH)/src/github.com/<your-username>/website
K8SROOT=$(GOPATH)/src/k8s.io/kubernetes
MINOR_VERSION=15

复制 OpenAPI 规范

<rdocs-base> 目录中运行以下命令:

make updateapispec

输出显示文件已被复制:

cp ~/src/k8s.io/kubernetes/api/openapi-spec/swagger.json gen-apidocs/generators/openapi-spec/swagger.json

构建 API 参考文档

<rdocs-base> 目录中运行以下命令:

make api

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

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

创建发布文档的目录

<web-base> 目录中为生成的 API 参考文件创建目录:

mkdir -p <web-base>/static/docs/reference/generated/kubernetes-api/v1.<minor-version>
mkdir -p <web-base>/static/docs/reference/generated/kubernetes-api/v1.<minor-version>/css
mkdir -p <web-base>/static/docs/reference/generated/kubernetes-api/v1.<minor-version>/fonts

将生成的文档复制到 kubernetes/website 仓库

<rdocs-base> 目录中运行以下命令,将生成的文件复制到本地 kubernetes/website 仓库。

make copyapi

进入 kubernetes/website 仓库的本地主目录,并查看已修改的文件:

cd <web-base>
git status

输出显示修改后的文件:

static/docs/reference/generated/kubernetes-api/v1.15/css/bootstrap.min.css
static/docs/reference/generated/kubernetes-api/v1.15/css/font-awesome.min.css
static/docs/reference/generated/kubernetes-api/v1.15/css/stylesheet.css
static/docs/reference/generated/kubernetes-api/v1.15/fonts/FontAwesome.otf
static/docs/reference/generated/kubernetes-api/v1.15/fonts/fontawesome-webfont.eot
static/docs/reference/generated/kubernetes-api/v1.15/fonts/fontawesome-webfont.svg
static/docs/reference/generated/kubernetes-api/v1.15/fonts/fontawesome-webfont.ttf
static/docs/reference/generated/kubernetes-api/v1.15/fonts/fontawesome-webfont.woff
static/docs/reference/generated/kubernetes-api/v1.15/fonts/fontawesome-webfont.woff2
static/docs/reference/generated/kubernetes-api/v1.15/index.html
static/docs/reference/generated/kubernetes-api/v1.15/jquery.scrollTo.min.js
static/docs/reference/generated/kubernetes-api/v1.15/navData.js
static/docs/reference/generated/kubernetes-api/v1.15/scroll.js

更新 API 参考索引页面

  • 打开 <web-base>/content/en/docs/reference/kubernetes-api/index.md 文件进行编辑,并且更新 API 参考版本号。例如:

    ---
    title: v1.15
    ---
    
    [Kubernetes API v1.15](/docs/reference/generated/kubernetes-api/v1.15/)
    
  • 打开 <web-base>/content/en/docs/reference/_index.md 文件进行编辑,并添加新链接以获取最新的 API 参考。移除最旧的 API 参考版本。应该有五个指向最新 API 参考的链接。

在本地测试 API 参考

发布 API 参考的本地版本。 验证 本地预览

cd <web-base>
make docker-serve

提交更改

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

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

接下来