Edit This Page

为 Kubernetes API 生成参考文档

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

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

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

准备开始

你需要安装以下软件：

你需要知道如何在一个 GitHub 项目仓库中创建一个 PR。一般来说，这涉及到创建仓库的 fork 分支。想了解更多信息，请参见创建一个文档 PR 和 GitHub 标准 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 add 和 git commit 来提交更改。

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

接下来