这是本节的多页打印视图。点击此处打印.

更新参考文档

1: 参考文档快速入门
2: 为发行版本生成参考文档
3: 为上游 Kubernetes 代码库做出贡献
4: 为 Kubernetes API 生成参考文档
5: 为 Configuration API 生成参考文档
6: 为 kubectl 命令集生成参考文档
7: 为指标生成参考文档
8: 为 Kubernetes 组件和工具生成参考文档
9:

本节的主题是描述如何生成 Kubernetes 参考指南。要生成参考文档，请参考下面的指南：

生成参考文档快速入门

1 - 参考文档快速入门

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

准备开始

需求

你需要一台 Linux 或 macOS 机器。在 Windows 上，请使用适用于 Linux 的 Windows 子系统（WS），因为构建工具依赖于 make 和 Bash 脚本。

你需要安装以下工具：
- Git
- Go，任意近期版本（Go 会自动下载生成器所需的特定工具链）
- make
- gcc compiler/linker
- Docker （仅在使用 make container-serve 进行本地网站预览时需要）

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

获取文档仓库

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

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/ 目录下，能够生成以下参考文档：

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

说明：

kubelet 参考页面不是由此脚本生成的，而是手动维护的。要更新 kubelet 参考，可以参考提 PR 所述的标准贡献流程。

脚本 update-imported-docs.py 基于 Kubernetes 源代码生成参考文档。过程中会在你的机器的 /tmp 目录下创建临时目录，克隆所需要的仓库 kubernetes/kubernetes 和 kubernetes-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 执行以下步骤：

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

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

配置文件格式

每个配置文件可以包含多个被导入的仓库。当必要时，你可以通过手工编辑此文件进行定制。你也可以通过创建新的配置文件来导入其他文档集合。下面是 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 版本依赖或者第三方库发生变化）。如果你遇到类似问题，请在 Kubernetes Slack 的 #sig-docs 频道联系 SIG-Docs 团队。

说明：

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

在 reference.yml 文件中，files 属性包含了一组 src 和 dst 字段。 src 字段给出在所克隆的 kubernetes-sigs/reference-docs 构造目录中生成的 Markdown 文件的位置，而 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

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

生成的 Kubernetes 组件文档

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.37/index.html
static/docs/reference/generated/kubernetes-api/v1.37/js/navData.js
static/docs/reference/generated/kubernetes-api/v1.37/js/scroll.js
static/docs/reference/generated/kubernetes-api/v1.37/js/query.scrollTo.min.js
static/docs/reference/generated/kubernetes-api/v1.37/css/font-awesome.min.css
static/docs/reference/generated/kubernetes-api/v1.37/css/bootstrap.min.css
static/docs/reference/generated/kubernetes-api/v1.37/css/stylesheet.css
static/docs/reference/generated/kubernetes-api/v1.37/fonts/FontAwesome.otf
static/docs/reference/generated/kubernetes-api/v1.37/fonts/fontawesome-webfont.eot
static/docs/reference/generated/kubernetes-api/v1.37/fonts/fontawesome-webfont.svg
static/docs/reference/generated/kubernetes-api/v1.37/fonts/fontawesome-webfont.ttf
static/docs/reference/generated/kubernetes-api/v1.37/fonts/fontawesome-webfont.woff
static/docs/reference/generated/kubernetes-api/v1.37/fonts/fontawesome-webfont.woff2

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

创建拉取请求

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

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

接下来

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

2 - 为发行版本生成参考文档

本页面介绍如何为新的发行版本重新生成每一套 Kubernetes 参考文档，以及如何将生成的输出拆分为多个拉取请求，以便评阅者能够逐个处理。

请按顺序阅读各个小节。每一套参考文档都有独立的小节，说明如何构建、如何将其复制到你的网站克隆中，并以一个待检查的页面收尾，这样你就可以在开始下一套之前先完成当前这一套。末尾的摘要列出了每个构建目标、其输出以及需要发起的拉取请求。

说明：

在发布周期内，这个过程由发布团队的文档负责人（Docs Lead）和文档影子（Docs shadow）来执行。 kubernetes/sig-release 中的 Docs 角色手册涵盖了该角色的其他内容。如果该手册增加了自己生成参考文档的步骤，请相应更新本页面。

准备开始

需求

你需要一台 Linux 或 macOS 机器。在 Windows 上，请使用适用于 Linux 的 Windows 子系统（WS），因为构建工具依赖于 make 和 Bash 脚本。

你需要安装以下工具：
- Git
- Go，任意近期版本（Go 会自动下载生成器所需的特定工具链）
- make
- gcc compiler/linker
- Docker （仅在使用 make container-serve 进行本地网站预览时需要）

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

配置本地仓库

你需要 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=<your-path-to>/website     # 你的网站克隆（<web-base>）
export K8S_RELEASE=1.38.0

将 K8S_RELEASE 设置为完整的发行版本号，例如 1.38.0 或 1.38.0-rc.1。构建目标会根据主版本号和次版本号推导出带版本号的目录名，例如 v1_38。

创建带版本号的目录

在 <rdocs-base> 中运行：

make createversiondirs

这会在 gen-apidocs/config/ 下为新发行版本创建配置目录，并从上一个发行版本复制 config.yaml。

你很少需要编辑该文件。随每个发行版本变化的那些设置，也就是 API 组和资源列表，在该文件中是空的：本页面的构建目标会传入 --auto-detect，因此生成器会从 swagger.json 中读取它们。文件中保留下来的是操作命名和排除规则，它们取决于 API 机制而不是 API 表面。

当生成的参考文档看起来有问题时，尽量在上游修复其根源：描述和弃用通知来自 kubernetes/kubernetes 中的 Go 注释，在那里修复能够惠及该 API 的所有读者。只有当某件事仅由生成器决定时才编辑 config.yaml，例如某个操作没有标题（operation_categories）、某个端点不应由参考文档发布（excluded_operations），或某个组的操作 ID 与其资源拼写不同（operation_group_map）。每个条目都会延续到之后的每个发行版本，因此请保持该文件精简。

获取 OpenAPI 规约

API 参考文档生成器会读取 gen-apidocs/config/<version>/swagger.json。 kubernetes/kubernetes 所提交的这份规约是在关闭 OpenAPIEnums 特性门控的情况下构建的，因此它省略了枚举字段的允许取值，基于它构建的参考文档也会省略这些取值。更好的做法是生成一份确实列出了允许取值的参考文档，为此你需要额外执行一些步骤。

从下面两个选项中选一个。

选项 1：从源码生成规约

除非你无法满足下面的要求，否则请使用此选项。它不需要你自己克隆 kubernetes/kubernetes，也不会改动你已有的任何克隆，并且它会生成包含枚举值的规约。

make updateapispec-enums-from-source

该目标会将 kubernetes/kubernetes 在标签 v$K8S_RELEASE 处浅克隆到一个临时目录，在这个检出中单独打开 OpenAPIEnums=true，运行上游的 hack/update-openapi-spec.sh，将生成的规约复制到带版本号的配置目录，检查其中是否包含枚举值，然后删除该检出。除前提条件中列出的工具外，它还需要：

在你的 PATH 中有 jq、curl 和 openssl
网络访问权限，用于克隆该标签以及下载 Go 模块和 etcd
空闲的 TCP 端口 2379 和 8050

上游脚本会在端口 2379 上启动 etcd，并在端口 8050 上启动一个临时 API 服务器；如果其中某个端口已被占用，请设置 ETCD_PORT 或 API_PORT。它会下载自己的 etcd 副本并构建 kube-apiserver，因此首次运行预计需要几分钟。

如需保留临时检出和生成日志以便排查问题：

KEEP_TMP=1 make updateapispec-enums-from-source

选项 2：在本地克隆中生成规约

如果你已经有一个 kubernetes/kubernetes 克隆，不想再要第二个，请使用此选项。你会跳过克隆步骤，但仍运行与选项 1 相同的生成器，而且它会修改你的克隆。

继续之前，请先提交或暂存克隆中已有的变更。将下面的路径替换为你的本地克隆路径，然后检出该发行版本的标签：

export K8S_ROOT="<your-path-to>/kubernetes"
cd "$K8S_ROOT"
git checkout "v$K8S_RELEASE"

然后在 hack/update-openapi-spec.sh 中设置 OpenAPIEnums=true 并运行它，以重新生成 api/openapi-spec/swagger.json。这需要选项 1 中描述的工具和空闲端口：

hack/update-openapi-spec.sh

说明：

如果不设置 OpenAPIEnums=true，规约中不会包含枚举值，已发布的 API 参考文档也会省略每个枚举字段的可能取值。

生成完成后，恢复该脚本：

git checkout -- hack/update-openapi-spec.sh

将重新生成的规约从你克隆的工作树复制到之前创建的带版本号的配置目录中。把 <rdocs-base> 替换为你的 reference-docs 克隆路径：

cd "<rdocs-base>"
cp "$K8S_ROOT/api/openapi-spec/swagger.json" \
  gen-apidocs/config/v1_38/swagger.json

检查规约

无论你使用哪个选项，都可以随时检查规约中是否包含枚举值：

./hack/verify-enum-swagger.sh gen-apidocs/config/<version>/swagger.json

启动本地预览

在第二个终端中启动一次预览，并让它保持运行。当各个复制目标替换页面时，Hugo 会重新加载每个页面，因此你生成完某一套参考文档后就能立即检查它。

cd <web-base>
git submodule update --init --recursive --depth 1   # 如果尚未完成
make container-serve

Hugo 在 http://localhost:1313/ 上提供预览。

说明：

每一套参考文档都应基于 <web-base> 中最新的分支开始，生成它、在预览中检查它，然后提交它。拉取请求列出了每一套参考文档需要发起什么、何时发起以及如何描述。

生成 Kubernetes API 参考文档

gen-apidocs 基于你获取的 OpenAPI 规约构建这一套参考文档，即 HTML 格式的 API 参考文档。构建输出会先出现在 gen-apidocs/build/html/ 中，然后由构建目标复制。

cd <rdocs-base>
make copyapi

该目标会将两个文件写入 <web-base>：

static/docs/reference/generated/kubernetes-api/v1.38/index.html
static/docs/reference/generated/kubernetes-api/v1.38/js/navData.js

在预览中检查 /docs/reference/generated/kubernetes-api/v1.38/。打开诸如 Pod 之类的资源，在页面中搜索 Possible enum values，即可确认规约确实带过来了枚举值。

关于这一套参考文档需要发起什么，请参见拉取请求。

生成 Markdown 格式的 API 参考页面

gen-apidocs 还会基于同一份规约构建这一套参考文档，即由 Hugo 渲染为普通页面的 Markdown 格式 API 参考文档。构建输出会出现在 gen-apidocs/build/markdown/ 中。

cd <rdocs-base>
make copyapimd

该目标会替换 <web-base>/content/en/docs/reference/kubernetes-api/，并保留由人工维护的 _index.md。

在预览中检查 /docs/reference/kubernetes-api/。将生成的页面数量与上一个发行版本进行比较：

find <web-base>/content/en/docs/reference/kubernetes-api -name '*.md' | wc -l

关于这一套参考文档需要发起什么，请参见拉取请求。

生成组件参考文档

gen-compdocs 基于 k8s.io/kubernetes 以及 go.mod 用 replace 指令固定版本的 k8s.io staging 模块进行构建。go get 只会更新前者而保留其余部分，因此需要一次性移动整个集合：

cd <rdocs-base>/gen-compdocs
STAGING=v0.${K8S_RELEASE#*.}
go get k8s.io/kubernetes@v$K8S_RELEASE
KK=$(go list -m -f '{{.Dir}}' k8s.io/kubernetes)

# 本发行版本的所有 staging 模块
for m in $(awk '/=> \.\/staging\/src\//{print $1}' "$KK/go.mod"); do
  go mod edit -replace="$m=$m@$STAGING" -require="$m@$STAGING"
done

# 来自 staging 模块集合不同的某个发行版本的残留条目
for m in $(go mod edit -json | jq -r '.Replace[].Old.Path'); do
  grep -q "$m => ./staging/src/$m" "$KK/go.mod" ||
    go mod edit -dropreplace="$m" -droprequire="$m"
done

go mod tidy
go mod edit -go=$(go list -m -f '{{.GoVersion}}' k8s.io/kubernetes)
go mod tidy

说明：

如果 go get 或 go mod tidy 针对某个 k8s.io 模块报告 unknown revision 或来自 sum.golang.org 的 404，说明本发行版本的 staging 模块尚未发布。它们会比 kubernetes/kubernetes 的标签晚几个小时。可以用下面的命令检查：

git ls-remote --tags https://github.com/kubernetes/api.git "v0.${K8S_RELEASE#*.}"

结果为空表示你需要等待。这也适用于 Configuration API 参考文档。那两套 API 参考文档只读取 OpenAPI 规约，因此你可以在此期间先生成它们。

这些循环从 kubernetes/kubernetes 读取模块集合，因为发行版本会增加和移除 staging 模块，而 go.mod 中仍可能列着较早发行版本的模块。 go 指示放在最后：当旧模块仍在依赖图中时，go mod tidy 会再次提升它。

检查有哪些变动：

git diff go.mod

现在每个 k8s.io 依赖项、每个 replace 以及 go 指示都应指向新的发行版本。 staging 集合之外的依赖项（例如 k8s.io/klog/v2 和 Goldmark 包）保留各自的版本。

然后构建并复制核心组件页面：

cd <rdocs-base>
make copycomp-core

gen-compdocs 会将每个组件页面写入 gen-compdocs/build/，该构建目标会把其中的 kube-apiserver.md、kube-controller-manager.md、 kube-scheduler.md、kube-proxy.md 和 kubelet.md 复制到 <web-base>/content/en/docs/reference/command-line-tools-reference/。

在预览中检查 /docs/reference/command-line-tools-reference/。

关于这一套参考文档需要发起什么，请参见拉取请求。

说明：

组件参考文档、kubectl 和 kubeadm 是三个独立的拉取请求，尽管 gen-compdocs 会同时产出这三者。每个 copycomp-* 目标都会先重新构建所有组件页面，这需要几分钟。如果想只构建一次并复制全部三套参考文档，可以运行 make copycomp，然后把结果拆分为三个分支。

生成 kubectl 参考文档

kubectl 页面与组件参考文档来自同一次 gen-compdocs 构建，但应放在各自的拉取请求中。

cd <rdocs-base>
make copycomp-kubectl

该目标会将 kubectl.md 以及每个子命令对应的目录写入 <web-base>/content/en/docs/reference/kubectl/generated/，并保留由人工维护的 _index.md。

在预览中检查 /docs/reference/kubectl/generated/，并打开某个子命令页面，例如 kubectl apply。

关于这一套参考文档需要发起什么，请参见拉取请求。

生成 kubeadm 参考文档

kubeadm 页面同样来自 gen-compdocs，但应放在各自的拉取请求中。

cd <rdocs-base>
make copycomp-kubeadm

该目标会将 kubeadm.md 以及每个子命令对应的目录写入 <web-base>/content/en/docs/reference/setup-tools/kubeadm/generated/，并保留由人工维护的 _index.md 和 README.md。

在预览中检查 /docs/reference/setup-tools/kubeadm/generated/。

关于这一套参考文档需要发起什么，请参见拉取请求。

生成 Configuration API 参考文档

genref 从 k8s.io staging 模块中读取每个组件的 Go 配置类型。它没有 replace 指令，因此仅由依赖项决定你为哪个发行版本编写文档：

cd <rdocs-base>/genref
STAGING=v0.${K8S_RELEASE#*.}
OLD=$(go mod edit -json | jq -r '.Require[] | select(.Path=="k8s.io/api") | .Version')

# 所有固定在上一发行版本的 k8s.io 模块
go get $(go mod edit -json | jq -r --arg v "$OLD" --arg s "$STAGING" \
  '.Require[] | select(.Version==$v and (.Path|startswith("k8s.io/"))) | .Path + "@" + $s')

go mod tidy
go mod edit -go=$(go list -m -f '{{.GoVersion}}' k8s.io/api)
go mod tidy

按旧版本进行选择可以挑选出 staging 模块，而不会去动 k8s.io/klog/v2、k8s.io/gengo 以及其他相互独立的仓库。检查有哪些变动：

git diff go.mod

还要更新 genref/config.yaml 中 externalPackages 链接目标所指向的发行版本，该目标用于把读者引向已发布的 API 参考文档。

检查新的 API 版本

genref 会为 genref/config.yaml 中的每个条目生成一个页面，每个条目都指定一个 Go 包以及一个以 API 版本结尾的路径：

  - name: kubelet-config
    title: Kubelet Configuration (v1)
    package: k8s.io/kubelet
    path: config/v1

某个组件在开始提供新版配置 API 时，会在其 Go 源码中新增一个版本目录。列出某个组件的版本目录，即可了解本发行版本中存在哪些版本：

cd <rdocs-base>/genref
go mod download
ls "$(go list -m -f '{{.Dir}}' k8s.io/kubelet)/config"

要一次性将 config.yaml 中的每个条目与源码进行比较，可以运行：

awk '$1=="package:"{pkg=$2} $1=="path:"{print pkg, $2}' config.yaml | sort -u |
while read -r pkg path; do
  dir=$(go list -m -f '{{.Dir}}' "$pkg" 2>/dev/null) || continue
  parent=$(dirname "$path")
  for v in $(find "$dir/$parent" -maxdepth 1 -mindepth 1 -type d -name 'v[0-9]*'); do
    grep -q "path: $parent/$(basename "$v")\$" config.yaml ||
      echo "$pkg $parent/$(basename "$v")"
  done
done | sort -u

每一行都只是一个候选项，而不是必须填补的空缺：有几个较早的版本是故意省略的， config.yaml 中的注释记录了原因。当某个组件提供读者需要配置的版本时，就添加一个条目；而当某个组件仍在提供较旧的版本时，应保留该版本的条目。

构建并复制页面

cd <rdocs-base>
make copyconfigapi

genref 会将生成的页面写入 genref/output/md/，而该构建目标在复制时会对其分类：大多数页面进入 content/en/docs/reference/config-api/，指标类 API 进入 content/en/docs/reference/external-api/，因为项目定义了这些 API 但并不通过 API 服务器提供它们，而网站不发布的页面会被跳过。

在预览中检查这两个部分，并确认你为上一个发行版本发布的页面没有消失：

cd <web-base>
git status content/en/docs/reference/config-api/ content/en/docs/reference/external-api/

关于这一套参考文档需要发起什么，请参见拉取请求。

摘要

参考文档集合、构建每一套文档的生成器及输出的落盘位置
参考文档集合	`<rdocs-base>` 中的生成器	构建目标	`<web-base>` 中的输出
Kubernetes API，HTML	`gen-apidocs`	`make copyapi`	`static/docs/reference/generated/kubernetes-api/v1.38/`
Kubernetes API，Markdown	`gen-apidocs`	`make copyapimd`	`content/en/docs/reference/kubernetes-api/`
组件	`gen-compdocs`	`make copycomp-core`	`content/en/docs/reference/command-line-tools-reference/`
kubectl	`gen-compdocs`	`make copycomp-kubectl`	`content/en/docs/reference/kubectl/generated/`
kubeadm	`gen-compdocs`	`make copycomp-kubeadm`	`content/en/docs/reference/setup-tools/kubeadm/generated/`
Configuration API	`genref`	`make copyconfigapi`	`content/en/docs/reference/config-api/`、`content/en/docs/reference/external-api/`

每个复制目标都会先执行构建。如果只想构建所有参考文档集合而不向网站克隆中复制任何内容，可以运行 make api apimd comp configapi。

拉取请求

每一套参考文档都有各自的网站拉取请求，总共六个，而生成器侧需要三个。请将网站拉取请求与它所需的 reference-docs 拉取请求一起发起，并等后者合并之后再处理网站侧的这个。

每一套参考文档需要发起的拉取请求
参考文档集合	向 `kubernetes-sigs/reference-docs` 发起的拉取请求	向 `kubernetes/website` 发起的拉取请求
Kubernetes API，HTML	`gen-apidocs/config/<version>/`，即配置和规约：两套 API 共用一个拉取请求	`Update the Kubernetes API reference for v1.38`
Kubernetes API，Markdown	同一个 `gen-apidocs` 拉取请求	`Update the generated API reference pages for v1.38`
组件	`gen-compdocs/go.mod` 和 `go.sum`：组件、kubectl 和 kubeadm 三套共用一个拉取请求	`Update the component reference for v1.38`
kubectl	同一个 `gen-compdocs` 拉取请求	`Update the kubectl reference for v1.38`
kubeadm	同一个 `gen-compdocs` 拉取请求	`Update the kubeadm reference for v1.38`
Configuration API	`genref/go.mod`、`genref/config.yaml` 和 `genref/output/md/`：共用一个拉取请求	`Update the configuration API reference for v1.38`

在每个网站拉取请求中，说明你是如何生成这些输出的，以便评阅者能够复现：

Regenerated the kubectl reference for v1.38.0.

- Generated with `make copycomp-kubectl` from kubernetes-sigs/reference-docs at commit <commit>
- Generator changes: kubernetes-sigs/reference-docs#<pull request>
- Generated files only, with no hand edits

对于那两套 API 参考文档，还要补充你是如何生成 OpenAPI 规约的，因为生成的输出中不会体现这一点：generated from source with OpenAPIEnums=true，或者从某个克隆中复制而来。

注意：

不要手工编辑生成的页面。下一个发行版本会覆盖该编辑。请改为在上游项目中或在生成器中修正措辞。

接下来

3 - 为上游 Kubernetes 代码库做出贡献

此页面描述如何为上游 kubernetes/kubernetes 项目做出贡献，如修复 Kubernetes API 文档或 Kubernetes 组件（例如 kubeadm、kube-apiserver、kube-controller-manager 等）中发现的错误。

如果你仅想从上游代码重新生成 Kubernetes API 或 kube-* 组件的参考文档。请参考以下说明：

准备开始

你需要安装以下工具：
- Git
- Golang 的 1.13 版本或更高
- Docker
- etcd
- make
- gcc compiler/linker

你必须设置 GOPATH 环境变量，并且 etcd 的位置必须在 PATH 环境变量中。

你需要知道如何创建对 GitHub 代码仓库的拉取请求（Pull Request）。通常，这涉及创建代码仓库的派生副本。要获取更多的信息请参考创建 PR 和 GitHub 标准派生和 PR 工作流程。

基本说明

Kubernetes API 和 kube-* 组件（例如 kube-apiserver、kube-controller-manager）的参考文档是根据上游 Kubernetes 中的源代码自动生成的。

当你在生成的文档中看到错误时，你可能需要考虑创建一个 PR 用来在上游项目中对其进行修复。

克隆 Kubernetes 代码仓库

如果你还没有 kubernetes/kubernetes 代码仓库，请参照下列命令获取：

mkdir $GOPATH/src
cd $GOPATH/src
go get github.com/kubernetes/kubernetes

确定你的 kubernetes/kubernetes 代码仓库克隆的根目录。例如，如果按照前面的步骤获取代码仓库，则你的根目录为 $GOPATH/src/github.com/kubernetes/kubernetes。接下来其余步骤将你的根目录称为 <k8s-base>。

确定你的 kubernetes-sigs/reference-docs 代码仓库克隆的根目录。例如，如果按照前面的步骤获取代码仓库，则你的根目录为 $GOPATH/src/github.com/kubernetes-sigs/reference-docs。接下来其余步骤将你的根目录称为 <rdocs-base>。

编辑 Kubernetes 源代码

Kubernetes API 参考文档是根据 OpenAPI 规范自动生成的，该规范是从 Kubernetes 源代码生成的。如果要更改 API 参考文档，第一步是更改 Kubernetes 源代码中的一个或多个注释。

kube-* 组件的文档也是从上游源代码生成的。你必须更改与要修复的组件相关的代码，才能修复生成的文档。

更改上游 Kubernetes 源代码

说明：

以下步骤仅作为示例，不是通用步骤，具体情况因环境而异。

以下在 Kubernetes 源代码中编辑注释的示例。

在你本地的 kubernetes/kubernetes 代码仓库中，检出默认分支，并确保它是最新的：

cd <k8s-base>
git checkout master
git pull https://github.com/kubernetes/kubernetes master

假设默认分支中的下面源文件中包含拼写错误 "atmost"：

kubernetes/kubernetes/staging/src/k8s.io/api/apps/v1/types.go

在你的本地环境中，打开 types.go 文件，然后将 "atmost" 更改为 "at most"。

以下命令验证你已经更改了文件：

git status

输出显示你在 master 分支上，types.go 源文件已被修改：

On branch master
...
    modified:   staging/src/k8s.io/api/apps/v1/types.go

提交已编辑的文件

运行 git add 和 git commit 命令提交到目前为止所做的更改。在下一步中，你将进行第二次提交，将更改分成两个提交很重要。

生成 OpenAPI 规范和相关文件

进入 <k8s-base> 目录并运行以下脚本：

./hack/update-codegen.sh
./hack/update-openapi-spec.sh

运行 git status 命令查看生成的文件。

On branch master
...
    modified:   api/openapi-spec/swagger.json
    modified:   api/openapi-spec/v3/apis__apps__v1_openapi.json
    modified:   pkg/generated/openapi/zz_generated.openapi.go
    modified:   staging/src/k8s.io/api/apps/v1/generated.proto
    modified:   staging/src/k8s.io/api/apps/v1/types_swagger_doc_generated.go

查看 api/openapi-spec/swagger.json 的内容，以确保拼写错误已经被修正。例如，你可以运行 git diff -a api/openapi-spec/swagger.json 命令。这很重要，因为 swagger.json 是文档生成过程中第二阶段的输入。

运行 git add 和 git commit 命令来提交你的更改。现在你有两个提交（commits）：一种包含编辑的 types.go 文件，另一种包含生成的 OpenAPI 规范和相关文件。将这两个提交分开独立。也就是说，不要 squash 你的提交。

将你的更改作为 PR 提交到 kubernetes/kubernetes 代码仓库的 master 分支。关注你的 PR，并根据需要回复 reviewer 的评论。继续关注你的 PR，直到 PR 被合并为止。

PR 57758 是修复 Kubernetes 源代码中的拼写错误的拉取请求的示例。

说明：

确定要更改的正确源文件可能很棘手。在前面的示例中，官方的源文件位于 kubernetes/kubernetes 代码仓库的 staging 目录中。但是根据你的情况，staging 目录可能不是找到官方源文件的地方。如果需要帮助，请阅读 kubernetes/kubernetes 代码仓库和相关代码仓库（例如 kubernetes/apiserver）中的 README 文件。

将你的提交 Cherrypick 到发布分支

在上一节中，你在 master 分支中编辑了一个文件，然后运行了脚本用来生成 OpenAPI 规范和相关文件。然后用 PR 将你的更改提交到 kubernetes/kubernetes 代码仓库的 master 分支中。现在，需要将你的更改反向移植到已经发布的分支。例如，假设 master 分支被用来开发 Kubernetes 1.37 版，并且你想将更改反向移植到 release-1.36 分支。

回想一下，你的 PR 有两个提交：一个用于编辑 types.go，一个用于由脚本生成的文件。下一步是将你的第一次提交 cherrypick 到 release-1.36 分支。这样做的原因是仅 cherrypick 编辑了 types.go 的提交，而不是具有脚本运行结果的提交。有关说明，请参见提出 Cherry Pick。

说明：

提出 Cherry Pick 要求你有权在 PR 中设置标签和里程碑。如果你没有这些权限，则需要与可以为你设置标签和里程碑的人员合作。

当你发起 PR 将你的一个提交 cherry pick 到 release-1.36 分支中时，下一步是在本地环境的 release-1.36 分支中运行如下脚本。

./hack/update-codegen.sh
./hack/update-openapi-spec.sh

现在将提交添加到你的 Cherry-Pick PR 中，该 PR 中包含最新生成的 OpenAPI 规范和相关文件。关注你的 PR，直到其合并到 release-1.36 分支中为止。

此时，master 分支和 release-1.36 分支都具有更新的 types.go 文件和一组生成的文件，这些文件反映了对 types.go 所做的更改。请注意，生成的 OpenAPI 规范和其他 release-1.36 分支中生成的文件不一定与 master 分支中生成的文件相同。 release-1.36 分支中生成的文件仅包含来自 Kubernetes 1.36 的 API 元素。 master 分支中生成的文件可能包含不在 1.36 中但正在为 1.37 开发的 API 元素。

生成已发布的参考文档

上一节显示了如何编辑源文件然后生成多个文件，包括在 kubernetes/kubernetes 代码仓库中的 api/openapi-spec/swagger.json。swagger.json 文件是 OpenAPI 定义文件，可用于生成 API 参考文档。

现在，你可以按照生成 Kubernetes API 的参考文档指南来生成已发布的 Kubernetes API 参考文档。

接下来

4 - 为 Kubernetes API 生成参考文档

本页面显示了如何更新 Kubernetes API 参考文档。

Kubernetes API 参考文档是从 Kubernetes OpenAPI 规范构建的，且使用 kubernetes-sigs/reference-docs 生成代码。

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

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

准备开始

需求

你需要一台 Linux 或 macOS 机器。在 Windows 上，请使用适用于 Linux 的 Windows 子系统（WS），因为构建工具依赖于 make 和 Bash 脚本。

你需要安装以下工具：
- Git
- Go，任意近期版本（Go 会自动下载生成器所需的特定工具链）
- make
- gcc compiler/linker
- Docker （仅在使用 make container-serve 进行本地网站预览时需要）

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

配置本地仓库

创建本地工作区并设置你的 GOPATH：

mkdir -p $HOME/<workspace>
export GOPATH=$HOME/<workspace>

获取以下仓库的本地克隆：

git clone github.com/kubernetes-sigs/reference-docs

将其移动到 reference-docs 仓库的 gen-apidocs 目录中，并安装所需的 Go 包：

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

克隆 kubernetes/kubernetes 仓库：

git clone https://github.com/kubernetes/kubernetes

kubernetes/kubernetes 仓库克隆后的根目录为 <your-path-to>/src/k8s.io/kubernetes。后续步骤将此目录称为 <k8s-base>。
kubernetes/website 仓库克隆后的根目录为 <your-path-to>/src/github.com/<your username>/website。后续步骤将此目录称为 <web-base>。
kubernetes-sigs/reference-docs 仓库克隆后的基本目录为 <your-path-to>/src/github.com/kubernetes-sigs/reference-docs。后续步骤将此目录称为 <rdocs-base>。

生成 API 参考文档

本节说明如何生成已发布的 Kubernetes API 参考文档。

设置构建变量

进入 <rdocs-base> 目录，然后打开 Makefile 文件进行编辑：

设置 K8S_ROOT 为 <k8s-base>。
设置 K8S_WEBROOT 为 <web-base>。
设置 K8S_RELEASE 为要构建的文档的版本。例如，如果你想为 Kubernetes 1.17.0 构建文档，请将 K8S_RELEASE 设置为 1.17.0。

例如：

export K8S_WEBROOT=<your-path-to>/website
export K8S_ROOT=<your-path-to>/kubernetes
export K8S_RELEASE=1.17.0

创建版本目录并复制 OpenAPI 规范

构建目标 updateapispec 负责创建版本化的构建目录。目录创建了之后，从 <k8s-base> 仓库取回 OpenAPI 规范文件。这些步骤确保配置文件的版本和 Kubernetes OpenAPI 规范的版本与发行版本匹配。版本化目录的名称形式为 v<major>_<minor>。

在 <rdocs-base> 目录中，运行以下命令来构建：

cd <rdocs-base>
make updateapispec

构建 API 参考文档

构建目标 copyapi 会生成 API 参考文档并将所生成文件复制到 <web-base 中的目录下。在 <rdocs-base> 目录中运行以下命令：

cd <rdocs-base>
make copyapi

验证是否已生成这两个文件：

[ -e "<rdocs-base>/gen-apidocs/build/index.html" ] && echo "index.html built" || echo "no index.html"
[ -e "<rdocs-base>/gen-apidocs/build/navData.js" ] && echo "navData.js built" || echo "no navData.js"

进入本地 <web-base> 目录，检查哪些文件被更改：

cd <web-base>
git status

输出类似于：

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

API 参考位置和版本控制

生成的 API 参考文件（HTML 版本）被复制到 <web-base>/static/docs/reference/generated/kubernetes-api/v1.37/。此目录包含了独立的 HTML API 文档。

说明：

API 参考的 Markdown 版本位于 <web-base>/content/en/docs/reference/kubernetes-api/，是使用 gen-resourcesdocs 生成器单独生成的。

在本地测试 API 参考

发布 API 参考的本地版本。检查本地预览。

cd <web-base>
git submodule update --init --recursive --depth 1 # 如果尚未完成
make container-serve

提交更改

在 <web-base> 中运行 git add 和 git commit 来提交更改。

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

接下来

5 - 为 Configuration API 生成参考文档

本页面展示了如何为 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。

如果你在生成的文档中发现错误，很可能需要在上游修复它们。

准备开始

需求

你需要一台 Linux 或 macOS 机器。在 Windows 上，请使用适用于 Linux 的 Windows 子系统（WS），因为构建工具依赖于 make 和 Bash 脚本。

你需要安装以下工具：
- Git
- Go，任意近期版本（Go 会自动下载生成器所需的特定工具链）
- make
- gcc compiler/linker
- Docker （仅在使用 make container-serve 进行本地网站预览时需要）

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

配置本地仓库

你需要 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/md
copyconfigapi - 将生成的文件复制到你的网站克隆的 <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 发起一个拉取请求。

接下来

6 - 为 kubectl 命令集生成参考文档

本页面描述了如何生成 kubectl 命令参考。

说明：

本主题描述了如何为 kubectl 命令生成参考文档，如 kubectl apply 和 kubectl taint。本主题没有讨论如何生成 kubectl 组件选项的参考页面。相关说明请参见为 Kubernetes 组件和工具生成参考页面。

准备开始

需求

你需要一台 Linux 或 macOS 机器。在 Windows 上，请使用适用于 Linux 的 Windows 子系统（WS），因为构建工具依赖于 make 和 Bash 脚本。

你需要安装以下工具：
- Git
- Go，任意近期版本（Go 会自动下载生成器所需的特定工具链）
- make
- gcc compiler/linker
- Docker （仅在使用 make container-serve 进行本地网站预览时需要）

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

配置本地仓库

创建本地工作区并设置你的 GOPATH：

mkdir -p $HOME/<workspace>
export GOPATH=$HOME/<workspace>

获取以下仓库的本地克隆：

go get -u github.com/spf13/pflag
go get -u github.com/spf13/cobra
go get -u gopkg.in/yaml.v2
go get -u kubernetes-incubator/reference-docs

如果你还没有获取过 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

从 $GOPATH/src/k8s.io/kubernetes/vendor/github.com 中移除 spf13 软件包：

rm -rf $GOPATH/src/k8s.io/kubernetes/vendor/github.com/spf13

kubernetes/kubernetes 仓库提供对 kubectl 和 kustomize 源代码的访问。

确定 kubernetes/kubernetes 仓库的本地主目录。例如，如果按照前面的步骤来获取该仓库，则主目录是 $GOPATH/src/k8s.io/kubernetes.。下文将该目录称为 <k8s-base>。

确定 kubernetes/website 仓库的本地主目录。例如，如果按照前面的步骤来获取该仓库，则主目录是 $GOPATH/src/github.com/<your-username>/website。下文将该目录称为 <web-base>。

确定 kubernetes-sigs/reference-docs 仓库的本地主目录。例如，如果按照前面的步骤来获取该仓库，则主目录是 $GOPATH/src/github.com/kubernetes-sigs/reference-docs。下文将该目录称为 <rdocs-base>。

在本地的 k8s.io/kubernetes 仓库中，检出感兴趣的分支并确保它是最新的。例如，如果你想要生成 Kubernetes 1.36.0 的文档，可以使用以下命令：

cd <k8s-base>
git checkout v1.36.0
git pull https://github.com/kubernetes/kubernetes 1.36.0

如果不需要编辑 kubectl 源码，请按照说明配置构建变量。

编辑 kubectl 源码

kubectl 命令的参考文档是基于 kubectl 源码自动生成的。如果想要修改参考文档，可以从修改 kubectl 源码中的一个或多个注释开始。在本地 kubernetes/kubernetes 仓库中进行修改，然后向 github.com/kubernetes/kubernetes 的 master 分支提交 PR。

PR 56673 是一个对 kubectl 源码中的笔误进行修复的 PR 示例。

跟踪你的 PR，并回应评审人的评论。继续跟踪你的 PR，直到它合入到 kubernetes/kubernetes 仓库的目标分支中。

以 cherry-pick 方式将你的修改合入已发布分支

你的修改已合入 master 分支中，该分支用于开发下一个 Kubernetes 版本。如果你希望修改部分出现在已发布的 Kubernetes 版本文档中，则需要提议将它们以 cherry-pick 方式合入已发布分支。

例如，假设 master 分支正用于开发 Kubernetes 1.37 版本，而你希望将修改合入到 release-1.36 版本分支。相关的操作指南，请参见提议一个 cherry-pick。

跟踪你的 cherry-pick PR，直到它合入到已发布分支中。

说明：

提议一个 cherry-pick 需要你有在 PR 中设置标签和里程碑的权限。如果你没有，你需要与有权限为你设置标签和里程碑的人合作完成。

设置构建变量

进入 <rdocs-base> 目录, 打开 Makefile 进行编辑：

设置 K8S_ROOT 为 <k8s-base>。
设置 K8S_WEBROOT 为 <web-base>。
设置 K8S_RELEASE 为要构建文档的版本。例如，如果你想为 Kubernetes 1.36 构建文档，请将 K8S_RELEASE 设置为 1.36。

例如：

export K8S_WEBROOT=$(GOPATH)/src/github.com/<your-username>/website
export K8S_ROOT=$(GOPATH)/src/k8s.io/kubernetes
export K8S_RELEASE=1.36

创建版本目录

构建目标 createversiondirs 会生成一个版本目录并将 kubectl 参考配置文件复制到该目录中。版本目录的名字模式为 v<major>_<minor>。

在 <rdocs-base> 目录下，执行下面的命令：

cd <rdocs-base>
make createversiondirs

从 kubernetes/kubernetes 检出一个分支

在本地 <k8s-base> 仓库中，检出你想要生成文档的、包含 Kubernetes 版本的分支。例如，如果希望为 Kubernetes 1.36.0 版本生成文档，请检出 v1.36 标记。确保本地分支是最新的。

cd <k8s-base>
git checkout v1.36.0
git pull https://github.com/kubernetes/kubernetes v1.36.0

运行文档生成代码

在本地的 <rdocs-base> 目录下，运行 copycli 构建目标。此命令以 root 账号运行：

cd <rdocs-base>
make copycli

copycli 命令将清理暂存目录，生成 kubectl 命令文件，并将整理后的 kubectl 参考 HTML 页面和文件复制到 <web-base>。

找到生成的文件

验证是否已生成以下两个文件：

[ -e "<rdocs-base>/gen-kubectldocs/generators/build/index.html" ] && echo "index.html built" || echo "no index.html"
[ -e "<rdocs-base>/gen-kubectldocs/generators/build/navData.js" ] && echo "navData.js built" || echo "no navData.js"

找到复制的文件

确认所有生成的文件都已复制到你的 <web-base>：

cd <web-base>
git status

输出应包括修改后的文件：

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/node_modules/font-awesome/css/font-awesome.min.css

在本地测试文档

在本地 <web-base> 中构建 Kubernetes 文档。

cd <web-base>
git submodule update --init --recursive --depth 1 # 如果还没完成
make container-serve

查看本地预览。

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

运行 git add 和 git commit 提交修改文件。

创建 PR

对 kubernetes/website 仓库创建 PR。跟踪你的 PR，并根据需要回应评审人的评论。继续跟踪你的 PR，直到它被合入。

在 PR 合入的几分钟后，你更新的参考主题将出现在已发布文档中。

接下来

7 - 为指标生成参考文档

本页演示如何生成指标参考文档。

准备开始

需求

你需要一台 Linux 或 macOS 机器。在 Windows 上，请使用适用于 Linux 的 Windows 子系统（WS），因为构建工具依赖于 make 和 Bash 脚本。

你需要安装以下工具：
- Git
- Go，任意近期版本（Go 会自动下载生成器所需的特定工具链）
- make
- gcc compiler/linker
- Docker （仅在使用 make container-serve 进行本地网站预览时需要）

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

克隆 Kubernetes 仓库

指标的生成发生在 Kubernetes 仓库中。要克隆此仓库，请将目录更改为你要克隆到的目标位置。

然后，执行以下命令：

git clone https://www.github.com/kubernetes/kubernetes

这将在当前工作目录中创建一个 kubernetes 文件夹。

生成指标

在克隆的 Kubernetes 仓库中，找到 test/instrumentation/documentation 目录。指标文档将在此目录中生成。

每次发布都会添加新的指标。你在运行指标文档生成脚本之后，将指标文档复制到 Kubernetes 网站并发布更新的指标文档。

要生成最新的指标，请确保你位于已克隆的 Kubernetes 仓库的根目录中。然后，执行以下命令：

./test/instrumentation/update-documentation.sh

要检查变更，执行以下命令：

git status

输出类似于：

./test/instrumentation/documentation/documentation.md
./test/instrumentation/documentation/documentation-list.yaml

将生成的指标文档文件复制到 Kubernetes 网站仓库

设置 Kubernetes 网站根环境变量
执行以下命令设置网站根目录：
```
export WEBSITE_ROOT=<path to website root>
```

将生成的指标文件复制到 Kubernetes 网站仓库。
```
cp ./test/instrumentation/documentation/documentation.md "${WEBSITE_ROOT}/content/en/docs/reference/instrumentation/metrics.md"
```
说明：
如果出现错误，请检查你是否有权限复制文件。你可以使用 chown 命令将文件所有权更改回你自己的用户。

创建 PR

要创建 PR，请按照提 PR 中的说明操作。

接下来

8 - 为 Kubernetes 组件和工具生成参考文档

本页面描述如何构造 Kubernetes 组件和工具的参考文档。

准备开始

阅读参考文档快速入门指南中的准备工作节。

按照参考文档快速入门指引，生成 Kubernetes 组件和工具的参考文档。

接下来

9 -

需求

你需要一台 Linux 或 macOS 机器。在 Windows 上，请使用适用于 Linux 的 Windows 子系统（WS），因为构建工具依赖于 make 和 Bash 脚本。

你需要安装以下工具：
- Git
- Go，任意近期版本（Go 会自动下载生成器所需的特定工具链）
- make
- gcc compiler/linker
- Docker （仅在使用 make container-serve 进行本地网站预览时需要）

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