为 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,直到合并为止。
接下来
反馈
此页是否对您有帮助?
感谢反馈。如果您有一个关于如何使用 Kubernetes 的特定的、需要答案的问题,可以访问 Stack Overflow. 在 GitHub 仓库上登记新的问题 报告问题 或者 提出改进建议.