本页面展示了如何为 Kubernetes Configuration API 生成更新的参考文档。 本文档面向为 Kubernetes 做贡献的人员。
Configuration API 参考文档记录了 Kubernetes 工具和组件的配置格式 — 例如
kubelet、kube-apiserver、kube-scheduler、kubeconfig 和 kubeadm 格式。
已发布的参考文档位于 /zh-cn/docs/reference/config-api/。
genref 是 kubernetes-sigs/reference-docs
中的生成器,用于构建此参考文档。它读取每个组件的 Go 配置类型并将其渲染为 Markdown。
如果你在生成的文档中发现错误, 很可能需要在上游修复它们。
配置本地仓库
你需要 kubernetes/website 和 kubernetes-sigs/reference-docs 的本地克隆。
如果你还没有复刻和克隆 kubernetes/website,
请参阅从本地克隆开始工作。
克隆 reference-docs:
git clone https://github.com/kubernetes-sigs/reference-docs
接下来的步骤将你的 kubernetes/website 克隆称为 <web-base>,
将你的 reference-docs 克隆称为 <rdocs-base>。
设置构建变量
在你的 Shell 中设置此变量。它适用于后续步骤中的每个 make 命令,
无论你在哪个目录下运行。
export K8S_WEBROOT=/path/to/your/website # your website clone (<web-base>)
构建和发布 Configuration API 参考
从 <rdocs-base> 开始:
cd <rdocs-base>
make copyconfigapi
此命令分两个阶段运行:
configapi- 构建并运行genref,生成 Markdown 到genref/output/mdcopyconfigapi- 将生成的文件复制到你的网站克隆的<web-base>/content/en/docs/reference/config-api/目录中。
首次运行会下载 Go 模块依赖项,可能需要几分钟。
检查你的网站克隆中的更改:
cd <web-base>
git status
查看 content/en/docs/reference/config-api 下所做的更新 —— 例如:
content/en/docs/reference/config-api/kubelet-config.v1beta1.md
content/en/docs/reference/config-api/kubeadm-config.v1beta4.md
content/en/docs/reference/config-api/apiserver-config.v1.md
content/en/docs/reference/config-api/client-authentication.v1.md
预览网站并在本地测试
预览你的更新:
cd <web-base>
git submodule update --init --recursive --depth 1 # 如果尚未完成
make container-serve
然后通过 Web 浏览器打开本地预览,确认你更新的页面能够正确加载。 Hugo 在 http://localhost:1313/ 提供本地预览, 因此要检查的页面是 http://localhost:1313/docs/reference/config-api/
提交更改
如果你为版本更新重新生成了 Configuration API 参考文档,
请在 <web-base> 中提交 content/en/docs/reference/config-api/ 下更改的文件,
然后向 kubernetes/website
发起一个拉取请求。
来源:Kubernetes 文档贡献者 · 作者与贡献记录 · CC BY 4.0。离线整理了版式、链接和媒体显示。
