为 Kubernetes 组件和工具生成参考页面
本页面展示了如何使用 update-imported-docs
工具来为 Kubernetes 和 Federation 仓库中的工具和组件生成参考文档。
- 准备开始
- 下载两个仓库
- 编辑 Kubernetes 源码
- 以 cherry-pick 方式将你的修改合入已发布分支
- update-imported-docs 概述
- 自定义 reference.yml 配置文件
- 运行 update-imported-docs 工具
- 在 kubernetes/website 中添加和提交修改
- 创建 PR
- 接下来
准备开始
- 你需要一个运行着 Linux 或 macOS 操作系统的机器。
你需要安装以下软件:
1.9或更高版本的 Golang
- 在环境变量中设置
$GOPATH
。
- 你需要知道如何在一个 GitHub 项目仓库中创建一个 PR。一般来说,这涉及到创建仓库的一个分支。想了解更多信息,请参见创建一个文档 PR。
下载两个仓库
如果你还没有下载过 kubernetes/website
仓库,现在下载:
mkdir $GOPATH/src
cd $GOPATH/src
go get github.com/kubernetes/website
确定 kubernetes/website 仓库的本地主目录。例如,如果按照前面的步骤来获取该仓库,则主目录是 $GOPATH/src/github.com/kubernetes/website
。下文将该目录称为 <web-base>
。
如果你想对参考文档进行修改,但是你还没下载过 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/kubernetes
仓库。当你运行update-imported-docs
工具时,它会自动克隆kubernetes/kubernetes
仓库。
编辑 Kubernetes 源码
Kubernetes 组件和工具的参考文档是基于 Kubernetes 源码自动生成的。如果想要修改参考文档,可以从修改 Kubernetes 源码中的一个或多个注释开始。在本地 kubernetes/kubernetes 仓库中进行修改,然后向 github.com/kubernetes/kubernetes 的 master 分支提交 PR。
PR 56942 是一个对 Kubernetes 源码中的注释进行修改的 PR 示例。
跟踪你的 PR,并回应评审人的评论。继续跟踪你的 PR,直到它合入到 kubernetes/kubernetes
仓库的 master 分支中。
以 cherry-pick 方式将你的修改合入已发布分支
你的修改已合入 master 分支中,该分支用于开发下一个 Kubernetes 版本。如果你希望修改部分出现在已发布的 Kubernetes 版本文档中,则需要提议将它们以 cherry-pick 方式合入已发布分支。
例如,假设 master 分支正用于开发 Kubernetes 1.10 版本,而你希望将修改合入到已发布的 1.9 版本分支。相关的操作指南,请参见 提议一个 cherry-pick 合入。
跟踪你的 cherry-pick PR,直到它合入到已发布分支中。
注意:提议一个 cherry-pick 合入,需要你有在 PR 中设置标签和里程碑的权限。如果你没有,你需要与有权限为你设置标签和里程碑的人合作完成。
update-imported-docs 概述
update-imported-docs
工具在 kubernetes/website/update-imported-docs/
目录下。它执行以下步骤:
- 克隆配置文件中指定的相关仓库。为了生成参考文档,默认情况下克隆的仓库是
kubernetes-incubator/reference-docs
和kubernetes/federation
。 - 在克隆出的仓库下运行命令来准备文档生成器,然后生成 Markdown 文件。
- 将生成的 Markdown 文件复制到配置文件中指定的
kubernetes/website
仓库的本地目录中。
当 Markdown 文件放入 kubernetes/website
仓库的本地目录中后,你就可以创建 PR 将它们提交到 kubernetes/website
。
自定义 reference.yml 配置文件
打开 <web-base>/update-imported-docs/reference.yml
进行编辑。不要修改 generate-command
条目的内容,除非你了解它的作用,并且需要修改指定的已发布分支。
repos:
- name: reference-docs
remote: https://github.com/kubernetes-sigs/reference-docs.git
# This and the generate-command below needs a change when reference-docs has
# branches properly defined
branch: master
generate-command: |
cd $GOPATH
git clone https://github.com/kubernetes/kubernetes.git src/k8s.io/kubernetes
cd src/k8s.io/kubernetes
git checkout release-1.17
make generated_files
cp -L -R vendor $GOPATH/src
rm -r vendor
cd $GOPATH
go get -v github.com/kubernetes-sigs/reference-docs/gen-compdocs
cd src/github.com/kubernetes-sigs/reference-docs/
make comp
在 reference.yml 中,files
字段是 src
和 dst
字段的列表。src
字段指定生成的 Markdown 文件的位置,而 dst
字段指定将此文件复制到 kubernetes/website
仓库的本地目录的哪个位置。例如:
repos:
- name: reference-docs
remote: https://github.com/kubernetes-incubator/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 工具
在检查与或自定义 reference.yaml
文件后,运行 update-imported-docs
工具:
cd <web-base>/update-imported-docs
./update-imported-docs reference.yml
在 kubernetes/website 中添加和提交修改
列出生成并准备合入到 kubernetes/website
仓库中的文件:
cd <web-base>
git status
输出展示了新增和修改的文件。例如,输出可能如下所示:
...
modified: content/en/docs/reference/command-line-tools-reference/cloud-controller-manager.md
modified: content/en/docs/reference/command-line-tools-reference/federation-apiserver.md
modified: content/en/docs/reference/command-line-tools-reference/federation-controller-manager.md
modified: content/en/docs/reference/command-line-tools-reference/kube-apiserver.md
modified: content/en/docs/reference/command-line-tools-reference/kube-controller-manager.md
modified: content/en/docs/reference/command-line-tools-reference/kube-proxy.md
modified: content/en/docs/reference/command-line-tools-reference/kube-scheduler.md
...
运行 git add
和 git commit
将提交上述文件。
创建 PR
对 kubernetes/website
仓库创建 PR。跟踪你的 PR,并根据需要回应评审人的评论。继续跟踪你的 PR,直到它被合入。
在 PR 合入的几分钟后,你更新的参考主题将出现在已发布文档中。
接下来
反馈
此页是否对您有帮助?
感谢反馈。如果您有一个关于如何使用 Kubernetes 的特定的、需要答案的问题,可以访问 Stack Overflow. 在 GitHub 仓库上登记新的问题 报告问题 或者 提出改进建议.