参考文档快速入门

本页面介绍如何使用 update-imported-docs.py 脚本生成 Kubernetes 参考文档。该脚本可自动执行构建设置并为发布版本生成参考文档。

准备工作

要求

您需要一台运行 Linux 或 macOS 的机器。
您需要安装以下工具
- Python v3.7.x+
- Git
- Golang 版本 1.13+
- Pip 用于安装 PyYAML
- PyYAML v5.1.2
- make
- gcc 编译器/链接器
- Docker (仅限 kubectl 命令参考)
您的 PATH 环境变量必须包含必需的构建工具，例如 Go 二进制文件和 python。
您需要了解如何向 GitHub 存储库创建拉取请求。这包括创建存储库的个人分支。有关更多信息，请参阅从本地克隆进行工作。

获取文档仓库

确保您的 website fork 与 GitHub 上的 kubernetes/website 远程仓库（main 分支）保持最新，并克隆您的 website fork。

mkdir github.com
cd github.com
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/ 目录下。

该脚本构建以下参考文档：

组件和工具参考页面
kubectl 命令参考
Kubernetes API 参考

注意

kubelet 参考页面不是由此脚本生成的，而是手动维护的。要更新 kubelet 参考，请遵循提交拉取请求中描述的标准贡献流程。

update-imported-docs.py 脚本从 Kubernetes 源代码生成 Kubernetes 参考文档。该脚本会在您的计算机上的 /tmp 下创建一个临时目录，并将所需的仓库 kubernetes/kubernetes 和 kubernetes-sigs/reference-docs 克隆到此目录中。该脚本将您的 GOPATH 设置为该临时目录。还会设置三个附加环境变量：

K8S_RELEASE
K8S_ROOT
K8S_WEBROOT

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

一个 YAML 配置文件 (reference.yml)
一个发布版本，例如：1.17

配置文件包含一个 generate-command 字段。generate-command 字段定义了来自 kubernetes-sigs/reference-docs/Makefile 的一系列构建指令。K8S_RELEASE 变量决定了发布版本。

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

克隆配置文件中指定的相关仓库。为了生成参考文档，默认克隆的仓库是 kubernetes-sigs/reference-docs。
在克隆的仓库下运行命令，以准备文档生成器，然后生成 HTML 和 Markdown 文件。
将生成的 HTML 和 Markdown 文件复制到 <web-base> 仓库的本地克隆中，具体位置由配置文件指定。
更新 kubectl 命令链接，从 kubectl.md 指向 kubectl 命令参考中的相关部分。

当生成的文件在 <web-base> 仓库的本地克隆中后，您可以将它们提交到 <web-base> 的拉取请求。

配置文件格式

每个配置文件可以包含多个将一起导入的仓库。如有必要，您可以手动编辑配置文件来自定义它。您可以创建新的配置文件来导入其他文档组。以下是 YAML 配置文件的一个示例：

repos:
- name: community
  remote: https://github.com/kubernetes/community.git
  branch: master
  files:
  - src: contributors/devel/README.md
    dst: docs/imported/community/devel.md
  - src: contributors/guide/README.md
    dst: docs/imported/community/guide.md

由工具导入的单页 Markdown 文档必须符合文档风格指南。

自定义 reference.yml

打开 <web-base>/update-imported-docs/reference.yml 进行编辑。除非您了解 generate-command 字段的用法，否则请勿更改其内容。您通常不需要更新 reference.yml。有时，上游源代码的更改可能需要更改配置文件（例如：golang 版本依赖和第三方库的更改）。如果您遇到构建问题，请在 #sig-docs Kubernetes Slack 频道上联系 SIG-Docs 团队。

注意

generate-command 是一个可选条目，可用于在仓库内运行给定命令或简短脚本来生成文档。

在 reference.yml 中，files 包含一个 src 和 dst 字段的列表。src 字段包含已生成 Markdown 文件在克隆的 kubernetes-sigs/reference-docs 构建目录中的位置，而 dst 字段指定将此文件复制到克隆的 kubernetes/website 仓库中的哪个位置。例如：

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

请注意，当有许多文件需要从同一源目录复制到同一目标目录时，您可以在 src 的值中使用通配符。您必须为 dst 提供目录名称作为值。例如：

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

运行 update-imported-docs 工具

您可以按以下方式运行 update-imported-docs.py 工具：

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

例如

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

修复链接

release.yml 配置文件包含修复相对链接的说明。要修复导入文件中的相对链接，请将 gen-absolute-links 属性设置为 true。您可以在 release.yml 中找到示例。

在 kubernetes/website 中添加和提交更改

列出已生成并复制到 <web-base> 的文件：

cd <web-base>
git status

输出显示了新修改的文件。生成的输出因上游源代码的更改而异。

生成的组件工具文件

content/en/docs/reference/command-line-tools-reference/kube-apiserver.md
content/en/docs/reference/command-line-tools-reference/kube-controller-manager.md
content/en/docs/reference/command-line-tools-reference/kube-proxy.md
content/en/docs/reference/command-line-tools-reference/kube-scheduler.md
content/en/docs/reference/setup-tools/kubeadm/generated/kubeadm.md
content/en/docs/reference/kubectl/kubectl.md

生成的 kubectl 命令参考文件

static/docs/reference/generated/kubectl/kubectl-commands.html
static/docs/reference/generated/kubectl/navData.js
static/docs/reference/generated/kubectl/scroll.js
static/docs/reference/generated/kubectl/stylesheet.css
static/docs/reference/generated/kubectl/tabvisibility.js
static/docs/reference/generated/kubectl/node_modules/bootstrap/dist/css/bootstrap.min.css
static/docs/reference/generated/kubectl/node_modules/highlight.js/styles/default.css
static/docs/reference/generated/kubectl/node_modules/jquery.scrollto/jquery.scrollTo.min.js
static/docs/reference/generated/kubectl/node_modules/jquery/dist/jquery.min.js
static/docs/reference/generated/kubectl/css/font-awesome.min.css

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

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

运行 git add 和 git commit 来提交文件。

创建拉取请求

向 kubernetes/website 仓库创建拉取请求。监控您的拉取请求，并根据需要回复审查意见。继续监控您的拉取请求，直到它被合并。

您的拉取请求合并几分钟后，您更新的参考主题将在已发布的文档中可见。

下一步

要通过手动设置所需的构建仓库并运行构建目标来生成单个参考文档，请参阅以下指南：

最后修改时间：2025 年 8 月 15 日上午 10:36 (太平洋标准时间)： docs: call out kubelet ref is manual (a6a64f4a80)