参考文档快速入门

本页讨论如何使用 update-imported-docs.py 脚本来生成 Kubernetes 参考文档。 此脚本将构建的配置过程自动化,并为某个发行版本生成参考文档。

准备开始

需求

  • 你需要一台 Linux 或 macOS 机器。

  • 你需要安装以下工具:

  • 你的 PATH 环境变量必须包含所需要的构建工具,例如 Go 程序和 python

  • 你需要知道如何为一个 GitHub 仓库创建拉取请求(PR)。 这牵涉到创建仓库的派生(fork)副本。 有关信息可进一步查看基于本地副本开展工作

获取文档仓库

确保你的 website 派生仓库与 GitHub 上的 kubernetes/website 远程仓库(main 分支)保持同步, 并克隆你的派生仓库。

  1. mkdir github.com
  2. cd github.com
  3. git clone git@github.com:<your_github_username>/website.git

确定你的克隆副本的根目录。例如,如果你按照前面的步骤获取了仓库,你的根目录 会是 github.com/website。接下来的步骤中,<web-base> 用来指代你的根目录。

说明:

如果你希望更改构建工具和 API 参考资料, 可以阅读上游贡献指南

update-imported-docs 的概述

脚本 update-imported-docs.py 位于 <web-base>/update-imported-docs/ 目录下, 能够生成以下参考文档:

  • Kubernetes 组件和工具的参考页面
  • kubectl 命令参考文档
  • Kubernetes API 参考文档

脚本 update-imported-docs.py 基于 Kubernetes 源代码生成参考文档。 过程中会在你的机器的 /tmp 目录下创建临时目录,克隆所需要的仓库 kubernetes/kuberneteskubernetes-sigs/reference-docs 到此临时目录。 脚本会将 GOPATH 环境变量设置为指向此临时目录。 此外,脚本会设置三个环境变量:

  • K8S_RELEASE
  • K8S_ROOT
  • K8S_WEBROOT

脚本需要两个参数才能成功运行:

  • 一个 YAML 配置文件(reference.yml
  • 一个发行版本字符串,例如:1.17

配置文件中包含 generate-command 字段,其中定义了一系列来自于 kubernetes-sigs/reference-docs/Makefile 的构建指令。 变量 K8S_RELEASE 用来确定所针对的发行版本。

脚本 update-imported-docs.py 执行以下步骤:

  1. 克隆配置文件中所指定的相关仓库。就生成参考文档这一目的而言,要克隆的仓库默认为 kubernetes-sigs/reference-docs
  2. 在所克隆的仓库下运行命令,准备文档生成器,之后生成 HTML 和 Markdown 文件。
  3. 将所生成的 HTML 和 Markdown 文件复制到 <web-base> 本地克隆副本中, 放在配置文件中所指定的目录下。
  4. 更新 kubectl.md 文件中对 kubectl 命令文档的链接,使之指向 kubectl 命令参考中对应的节区。

当所生成的文件已经被放到 <web-base> 目录下,你就可以将其提交到你的派生副本中, 并基于所作提交发起拉取请求(PR)到 kubernetes/website 仓库。

配置文件格式

每个配置文件可以包含多个被导入的仓库。当必要时,你可以通过手工编辑此文件进行定制。 你也可以通过创建新的配置文件来导入其他文档集合。 下面是 YAML 配置文件的一个例子:

  1. repos:
  2. - name: community
  3. remote: https://github.com/kubernetes/community.git
  4. branch: master
  5. files:
  6. - src: contributors/devel/README.md
  7. dst: docs/imported/community/devel.md
  8. - src: contributors/guide/README.md
  9. dst: docs/imported/community/guide.md

通过工具导入的单页面的 Markdown 文档必须遵从文档样式指南

定制 reference.yml

打开 <web-base>/update-imported-docs/reference.yml 文件进行编辑。 在不了解参考文档构造命令的情况下,不要更改 generate-command 字段的内容。 你一般不需要更新 reference.yml 文件。不过也有时候上游的源代码发生变化, 导致需要对配置文件进行更改(例如:Golang 版本依赖或者第三方库发生变化)。 如果你遇到类似问题,请在 Kubernetes Slack 的 #sig-docs 频道 联系 SIG-Docs 团队。

说明:

注意,generate-command 是一个可选项,用来运行指定命令或者短脚本以在仓库内生成文档。

reference.yml 文件中,files 属性包含了一组 srcdst 字段。 src 字段给出在所克隆的 kubernetes-sigs/reference-docs 构造目录中生成的 Markdown 文件的位置,而 dst 字段则给出了对应文件要复制到的、所克隆的 kubernetes/website 仓库中的位置。例如:

  1. repos:
  2. - name: reference-docs
  3. remote: https://github.com/kubernetes-sigs/reference-docs.git
  4. files:
  5. - src: gen-compdocs/build/kube-apiserver.md
  6. dst: content/en/docs/reference/command-line-tools-reference/kube-apiserver.md
  7. ...

注意,如果从同一源目录中有很多文件要复制到目标目录,你可以在为 src 所设置的值中使用通配符。这时,为 dst 所设置的值必须是目录名称。例如:

  1. files:
  2. - src: gen-compdocs/build/kubeadm*.md
  3. dst: content/en/docs/reference/setup-tools/kubeadm/generated/

运行 update-imported-docs 工具

你可以用如下方式运行 update-imported-docs.py 工具:

  1. cd <web-base>/update-imported-docs
  2. ./update-imported-docs.py <configuration-file.yml> <release-version>

例如:

  1. ./update-imported-docs.py reference.yml 1.17

修复链接

配置文件 release.yml 中包含用来修复相对链接的指令。 若要修复导入文件中的相对链接,将 gen-absolute-links 属性设置为 true。你可以在 release.yml 文件中找到示例。

添加并提交 kubernetes/website 中的变更

枚举新生成并复制到 <web-base> 的文件:

  1. cd <web-base>
  2. git status

输出显示新生成和已修改的文件。取决于上游源代码的修改多少, 所生成的输出也会不同。

生成的 Kubernetes 组件文档

  1. content/en/docs/reference/command-line-tools-reference/cloud-controller-manager.md
  2. content/en/docs/reference/command-line-tools-reference/kube-apiserver.md
  3. content/en/docs/reference/command-line-tools-reference/kube-controller-manager.md
  4. content/en/docs/reference/command-line-tools-reference/kube-proxy.md
  5. content/en/docs/reference/command-line-tools-reference/kube-scheduler.md
  6. content/en/docs/reference/setup-tools/kubeadm/generated/kubeadm.md
  7. content/en/docs/reference/kubectl/kubectl.md

生成的 kubectl 命令参考文件

  1. static/docs/reference/generated/kubectl/kubectl-commands.html
  2. static/docs/reference/generated/kubectl/navData.js
  3. static/docs/reference/generated/kubectl/scroll.js
  4. static/docs/reference/generated/kubectl/stylesheet.css
  5. static/docs/reference/generated/kubectl/tabvisibility.js
  6. static/docs/reference/generated/kubectl/node_modules/bootstrap/dist/css/bootstrap.min.css
  7. static/docs/reference/generated/kubectl/node_modules/highlight.js/styles/default.css
  8. static/docs/reference/generated/kubectl/node_modules/jquery.scrollto/jquery.scrollTo.min.js
  9. static/docs/reference/generated/kubectl/node_modules/jquery/dist/jquery.min.js
  10. static/docs/reference/generated/kubectl/css/font-awesome.min.css

生成的 Kubernetes API 参考目录与文件

  1. static/docs/reference/generated/kubernetes-api/v1.27/index.html
  2. static/docs/reference/generated/kubernetes-api/v1.27/js/navData.js
  3. static/docs/reference/generated/kubernetes-api/v1.27/js/scroll.js
  4. static/docs/reference/generated/kubernetes-api/v1.27/js/query.scrollTo.min.js
  5. static/docs/reference/generated/kubernetes-api/v1.27/css/font-awesome.min.css
  6. static/docs/reference/generated/kubernetes-api/v1.27/css/bootstrap.min.css
  7. static/docs/reference/generated/kubernetes-api/v1.27/css/stylesheet.css
  8. static/docs/reference/generated/kubernetes-api/v1.27/fonts/FontAwesome.otf
  9. static/docs/reference/generated/kubernetes-api/v1.27/fonts/fontawesome-webfont.eot
  10. static/docs/reference/generated/kubernetes-api/v1.27/fonts/fontawesome-webfont.svg
  11. static/docs/reference/generated/kubernetes-api/v1.27/fonts/fontawesome-webfont.ttf
  12. static/docs/reference/generated/kubernetes-api/v1.27/fonts/fontawesome-webfont.woff
  13. static/docs/reference/generated/kubernetes-api/v1.27/fonts/fontawesome-webfont.woff2

运行 git addgit commit 提交文件。

创建拉取请求

接下来创建一个对 kubernetes/website 仓库的拉取请求(PR)。 监视所创建的 PR,并根据需要对评阅意见给出反馈。 继续监视该 PR 直到其被合并为止。

当你的 PR 被合并几分钟之后,你所做的对参考文档的变更就会出现 发布的文档上。

接下来

要手动设置所需的构造仓库,执行构建目标,以生成各个参考文档,可参考下面的指南: