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

返回本页常规视图.

更新参考文档

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

1 - 参考文档快速入门

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

准备开始

需求

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

  • 你需要知道如何为一个 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> 用来指代你的根目录。

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 配置文件的一个例子:

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 团队。

reference.yml 文件中,files 属性包含了一组 srcdst 字段。 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/cloud-controller-manager.md
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.29/index.html
static/docs/reference/generated/kubernetes-api/v1.29/js/navData.js
static/docs/reference/generated/kubernetes-api/v1.29/js/scroll.js
static/docs/reference/generated/kubernetes-api/v1.29/js/query.scrollTo.min.js
static/docs/reference/generated/kubernetes-api/v1.29/css/font-awesome.min.css
static/docs/reference/generated/kubernetes-api/v1.29/css/bootstrap.min.css
static/docs/reference/generated/kubernetes-api/v1.29/css/stylesheet.css
static/docs/reference/generated/kubernetes-api/v1.29/fonts/FontAwesome.otf
static/docs/reference/generated/kubernetes-api/v1.29/fonts/fontawesome-webfont.eot
static/docs/reference/generated/kubernetes-api/v1.29/fonts/fontawesome-webfont.svg
static/docs/reference/generated/kubernetes-api/v1.29/fonts/fontawesome-webfont.ttf
static/docs/reference/generated/kubernetes-api/v1.29/fonts/fontawesome-webfont.woff
static/docs/reference/generated/kubernetes-api/v1.29/fonts/fontawesome-webfont.woff2

运行 git addgit commit 提交文件。

创建拉取请求

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

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

接下来

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

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

此页面描述如何为上游 kubernetes/kubernetes 项目做出贡献,如修复 Kubernetes API 文档或 Kubernetes 组件(例如 kubeadmkube-apiserverkube-controller-manager 等) 中发现的错误。

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

准备开始

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

基本说明

Kubernetes API 和 kube-* 组件(例如 kube-apiserverkube-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 addgit 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 addgit commit 命令来提交你的更改。现在你有两个提交(commits): 一种包含编辑的 types.go 文件,另一种包含生成的 OpenAPI 规范和相关文件。 将这两个提交分开独立。也就是说,不要 squash 你的提交。

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

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

将你的提交 Cherrypick 到发布分支

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

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

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

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

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

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

生成已发布的参考文档

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

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

接下来

3 - 为 Kubernetes API 生成参考文档

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

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

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

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

准备开始

需求

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

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

配置本地仓库

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

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

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

go get -u github.com/kubernetes-sigs/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-sigs/reference-docs 仓库克隆后的基本目录为 $GOPATH/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=${GOPATH}/src/github.com/<your-username>/website
export K8S_ROOT=${GOPATH}/src/k8s.io/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.29/css/bootstrap.min.css
static/docs/reference/generated/kubernetes-api/v1.29/css/font-awesome.min.css
static/docs/reference/generated/kubernetes-api/v1.29/css/stylesheet.css
static/docs/reference/generated/kubernetes-api/v1.29/fonts/FontAwesome.otf
static/docs/reference/generated/kubernetes-api/v1.29/fonts/fontawesome-webfont.eot
static/docs/reference/generated/kubernetes-api/v1.29/fonts/fontawesome-webfont.svg
static/docs/reference/generated/kubernetes-api/v1.29/fonts/fontawesome-webfont.ttf
static/docs/reference/generated/kubernetes-api/v1.29/fonts/fontawesome-webfont.woff
static/docs/reference/generated/kubernetes-api/v1.29/fonts/fontawesome-webfont.woff2
static/docs/reference/generated/kubernetes-api/v1.29/index.html
static/docs/reference/generated/kubernetes-api/v1.29/js/jquery.scrollTo.min.js
static/docs/reference/generated/kubernetes-api/v1.29/js/navData.js
static/docs/reference/generated/kubernetes-api/v1.29/js/scroll.js

更新 API 参考索引页面

在为新发行版本生成参考文档时,需要更新下面的文件,使之包含新的版本号: <web-base>/content/en/docs/reference/kubernetes-api/api-index.md

  • 打开并编辑 <web-base>/content/en/docs/reference/kubernetes-api/api-index.md, API 参考的版本号。例如:

    title: v1.17
    [Kubernetes API v1.17](/docs/reference/generated/kubernetes-api/v1.17/)
    
  • 打开编辑 <web-base>/content/en/docs/reference/_index.md,添加指向最新 API 参考的链接,删除最老的 API 版本。 通常保留最近的五个版本的 API 参考的链接。

在本地测试 API 参考

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

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

提交更改

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

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

接下来

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

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

准备开始

需求

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

  • 你需要知道如何为一个 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.28.0 的文档,可以使用以下命令:

cd <k8s-base>
git checkout v1.28.0
git pull https://github.com/kubernetes/kubernetes 1.28.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.29 版本, 而你希望将修改合入到 release-1.28 版本分支。 相关的操作指南,请参见 提议一个 cherry-pick

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

设置构建变量

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

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

例如:

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

创建版本目录

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

<rdocs-base> 目录下,执行下面的命令:

cd <rdocs-base>
make createversiondirs

从 kubernetes/kubernetes 检出一个分支

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

cd <k8s-base>
git checkout v1.28.0
git pull https://github.com/kubernetes/kubernetes v1.28.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 addgit commit 提交修改文件。

创建 PR

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

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

接下来

5 - 为指标生成参考文档

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

准备开始

需求

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

  • 你需要知道如何为一个 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 网站仓库

  1. 设置 Kubernetes 网站根环境变量

    执行以下命令设置网站根目录:

    export WEBSITE_ROOT=<path to website root>
    
  1. 将生成的指标文件复制到 Kubernetes 网站仓库。

    cp ./test/instrumentation/documentation/documentation.md "${WEBSITE_ROOT}/content/en/docs/reference/instrumentation/metrics.md"
    

创建 PR

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

接下来

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

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

准备开始

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

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

接下来

7 -

需求

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

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