參考文件快速入門

本頁面介紹如何使用 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)