您正在查看 Kubernetes 版本的文档: v1.18
Kubernetes v1.18 版本的文档已不再维护。您现在看到的版本来自于一份静态的快照。如需查阅最新文档,请点击 最新版本。
文档样式指南
本页讨论 Kubernetes 文档的样式指南。 这些仅仅是指南而不是规则。 你可以自行决定,且欢迎使用 PR 来为此文档提供修改意见。
关于为 Kubernetes 文档贡献新内容的更多信息,可以参考 文档内容指南。
样式指南的变更是 SIG Docs 团队集体决定。 如要提议更改或新增条目,请先将其添加到下一次 SIG Docs 例会的 议程表 上,并按时参加会议讨论。
说明: Kubernetes 文档使用带调整的 Goldmark Markdown 解释器 和一些 Hugo 短代码 来支持词汇表项、Tab 页以及特性门控标注。
语言
Kubernetes 文档已经被翻译为多个语种 (参见 本地化 READMEs)。
为文档提供一种新的语言翻译的途径可以在 本地化 Kubernetes 文档中找到。
英语文档使用美国英语的拼写和语法。
文档格式标准
对 API 对象使用驼峰式命名法
当指代 API 对象时,请使用与实际对象名称中一样的大写和小写字母。 通常 API 对象使用驼峰式命名.
不要将 API 对象的名称切分成多个单词。例如,使用 PodTemplateList,不要 使用 Pod Template List。
引用 API 对象时不必强调 “object(对象)”,除非省略“object(object)” 会使得文字读起来很别扭。
可以 | 不可以 |
---|---|
Pod 有两个容器 | pod 中有两个容器 |
此 Deployment 负责... | 此 Deployment 对象负责 ... |
PodList 是 Pod 的列表 | Pod List 是 pods 的列表 |
这两个 ContainerPorts ... | 这两个 ContainerPort 对象 ... |
这两个 ContainerStateTerminated 对象 ... | 这两个 ContainerStateTerminateds ... |
在占位符中使用尖括号
在占位符中使用尖括号,并让读者知道其中代表的事物。例如:
显示 Pod 信息:
kubectl describe pod <pod-名称> -n <名字空间>
如果名字空间被忽略,默认为
default
,你可以忽略 '-n' 参数。
用粗体字表现用户界面元素
可以 | 不可以 |
---|---|
点击 Fork. | 点击 "Fork". |
选择 Other. | 选择 "Other". |
定义或引入新术语时使用斜体
可以 | 不可以 |
---|---|
每个 集群 是一组节点 ... | 每个“集群”是一组节点 ... |
这些组件构成了 控制面. | 这些组件构成了 控制面. |
使用代码样式表现文件名、目录和路径
可以 | 不可以 |
---|---|
打开 envars.yaml 文件 | 打开 envars.yaml 文件 |
进入到 /docs/tutorials 目录 | 进入到 /docs/tutorials 目录 |
打开 /_data/concepts.yaml 文件 | 打开 /_data/concepts.yaml 文件 |
在引号内使用国际标准标点
可以 | 不可以 |
---|---|
事件记录中都包含对应的“stage”。 | 事件记录中都包含对应的“stage。” |
此副本称作一个“fork”。 | 此副本称作一个“fork。” |
行间代码格式
为行间代码和命令使用代码样式
对于 HTML 文档中的行间代码,使用 <code>
标记。
在 Markdown 文档中,使用反引号(`
)。
可以 | 不可以 |
---|---|
命令 kubectl run 会创建一个 Deployment | 命令 "kubectl run" 会创建一个 Deployment。 |
在声明式管理中,使用 kubectl apply 。 | 在声明式管理中,使用 "kubectl apply"。 |
用三个反引号来(```)标示代码示例 | 用其他语法来标示代码示例。 |
使用单个反引号来标示行间代码。例如:var example = true 。 | 使用两个星号(** )或者一个下划线(_ )来标示行间代码。例如:var example = true。 |
在多行代码块之前和之后使用三个反引号标示隔离的代码块。 | 使用多行代码块来创建示意图、流程图或者其他表示。 |
使用符合上下文的有意义的变量名。 | 使用诸如 'foo'、'bar' 和 'baz' 这类无意义且无语境的变量名。 |
删除代码中行尾空白。 | 在代码中包含行尾空白,因为屏幕抓取工具通常也会抓取空白字符。 |
说明: 网站支持为代码示例使用语法加亮,不过指定语法加亮是可选的。 代码段的语法加亮要遵从对比度指南
为对象字段名和名字空间使用代码风格
可以 | 不可以 |
---|---|
在配置文件中设置 replicas 字段的值。 | 在配置文件中设置 "replicas" 字段的值。 |
exec 字段的值是一个 ExecAction 对象。 | "exec" 字段的值是一个 ExecAction 对象。 |
在 kube-system 名字空间中以 Daemonset 形式运行此进程。 | 在 kube-system 名字空间中以 DaemonSet 形式运行此进程。 |
用代码样式书写 Kubernetes 命令工具和组件名
可以 | 不可以 |
---|---|
kubelet 维持节点稳定性。 | kubelet 负责维护节点稳定性。 |
kubectl 处理 API 服务器的定位和身份认证。 | kubectl 处理 API 服务器的定位和身份认证。 |
使用该证书运行进程 kube-apiserver --client-ca-file=FILENAME . | 使用证书运行进程 kube-apiserver --client-ca-file=FILENAME. |
用工具或组件名称开始一句话
可以 | 不可以 |
---|---|
The kubeadm tool bootstraps and provisions machines in a cluster. | kubeadm tool bootstraps and provisions machines in a cluster. |
The kube-scheduler is the default scheduler for Kubernetes. | kube-scheduler is the default scheduler for Kubernetes. |
尽量使用通用描述而不是组件名称
可以 | 不可以 |
---|---|
Kubernetes API 服务器提供 OpenAPI 规范。 | apiserver 提供 OpenAPI 规范 |
聚合 APIs 是下级 API 服务器。 | 聚合 APIs 是下级 APIServers。 |
使用普通样式表达字符串和整数字段值
对于字符串或整数,使用正常样式,不要带引号。
可以 | 不可以 |
---|---|
将 imagePullPolicy 设置为 Always。 | 将 imagePullPolicy 设置为 "Always"。 |
将 image 设置为 nginx:1.16. | 将 image 设置为 nginx:1.16 。 |
将 replicas 字段值设置为 2. | 将 replicas 字段值设置为 2 . |
代码段格式
不要包含命令行提示符
可以 | 不可以 |
---|---|
kubectl get pods | $ kubectl get pods |
将命令和输出分开
例如:
验证 Pod 已经在你所选的节点上运行:
kubectl get pods --output=wide
输出类似于:
NAME READY STATUS RESTARTS AGE IP NODE
nginx 1/1 Running 0 13s 10.200.0.4 worker0
为 Kubernetes 示例给出版本
代码示例或者配置示例如果包含版本信息,应该与对应的文字描述一致。
如果所给的信息是特定于具体版本的,需要在
任务模版
或教程模版
的 prerequisites
小节定义 Kubernetes 版本。
页面保存之后,prerequisites
小节会显示为 开始之前。
如果要为任务或教程页面指定 Kubernetes 版本,可以在文件的前言部分包含
min-kubernetes-server-version
信息。
如果示例 YAML 是一个独立文件,找到并审查包含该文件的主题页面。 确认使用该独立 YAML 文件的主题都定义了合适的版本信息。 如果独立的 YAML 文件没有在任何主题中引用,可以考虑删除该文件, 而不是继续更新它。
例如,如果你在编写一个教程,与 Kubernetes 1.8 版本相关。那么你的 Markdown 文件的文件头应该开始起来像这样:
---
title: <教程标题>
min-kubernetes-server-version: v1.8
---
在代码和配置示例中,不要包含其他版本的注释信息。 尤其要小心不要在示例中包含不正确的注释信息,例如:
apiVersion: v1 # 早期版本使用...
kind: Pod
...
Kubernetes.io 术语列表
以下特定于 Kubernetes 的术语和词汇在使用时要保持一致性。
术语 | 用法 |
---|---|
Kubernetes | Kubernetes 的首字母要保持大写。 |
Docker | Docker 的首字母要保持大写。 |
SIG Docs | SIG Docs 是正确拼写形式,不要用 SIG-DOCS 或其他变体。 |
On-premises | On-premises 或 On-prem 而不是 On-premise 或其他变体。 |
短代码(Shortcodes)
Hugo 短代码(Shortcodes)
有助于创建比较漂亮的展示效果。我们的文档支持三个不同的这类短代码。
注意 {{< note >}}
、小心 {{< caution >}}
和 警告 {{< warning >}}
。
将要突出显示的文字用短代码的开始和结束形式包围。
使用下面的语法来应用某种样式:
{{< note >}} 不需要前缀;短代码会自动添加前缀(注意:、小心:等) {{< /note >}}
输出的样子是:
说明: 你所选择的标记决定了文字的前缀。
注释(Note)
使用短代码 {{< note >}}
来突出显示某种提示或者有助于读者的信息。
例如:
{{< note >}}
在这类短代码中仍然 _可以_ 使用 Markdown 语法。
{{< /note >}}
输出为:
说明: 在这类短代码中仍然 可以 使用 Markdown 语法。
你可以在列表中使用 {{< note >}}
:
1. 在列表中使用 note 短代码
1. 带嵌套 note 的第二个条目
{{< note >}}
警告、小心和注意短代码可以嵌套在列表中,但是要缩进四个空格。
参见[常见短代码问题](#common-shortcode-issues)。
{{< /note >}}
1. 列表中第三个条目
1. 列表中第四个条目
其输出为:
在列表中使用 note 短代码
带嵌套 note 的第二个条目
说明: 警告、小心和注意短代码可以嵌套在列表中,但是要缩进四个空格。 参见常见短代码问题。列表中第三个条目
列表中第四个条目
小心(Caution)
使用 {{< caution >}}
短代码来引起读者对某段信息的重视,以避免遇到问题。
例如:
{{< caution >}}
此短代码样式仅对标记之上的一行起作用。
{{< /caution >}}
其输出为:
注意: 此短代码样式仅对标记之上的一行起作用。
警告(Warning)
使用 {{< warning >}}
来表明危险或者必须要重视的一则信息。
例如:
{{< warning >}}
注意事项
{{< /warning >}}
其输出为:
警告: 注意事项
Katacoda 嵌套现场环境
此按钮允许用户使用 Katacoda 终端 在其浏览器中运行 Minikube。该环境降低了用户对 Minikube 的入门难度, 只需要一次鼠标点击即可完成,而不需要完全经历 Minikube 和 kubectl 的安装过程。
嵌套现场环境配置为运行 minikube start
,允许用户在文档所在的窗口完成教程。
注意: 会话限制为 15 分钟。
例如:
{{< kat-button >}}
其输出为:
常见的短代码问题
编号列表
短代码会打乱编号列表的编号,除非你在信息和标志之前都缩进四个空格。
例如:
1. 预热到 350˚F
1. 准备好面糊,倒入烘烤盘
{{< note >}}给盘子抹上油可以达到最佳效果。{{< /note >}}
1. 烘烤 20 到 25 分钟,或者直到满意为止。
其输出结果为:
- 预热到 350˚F
- 准备好面糊,倒入烘烤盘说明: 给盘子抹上油可以达到最佳效果。
- 烘烤 20 到 25 分钟,或者直到满意为止。
Include 语句
如果短代码出现在 include 语境中,会导致网站无法构建。 你必须将他们插入到上级文档中,分别将开始标记和结束标记插入到 include 语句之前和之后。 例如:
{{< note >}}
{{< include "task-tutorial-prereqs.md" >}}
{{< /note >}}
Markdown 元素
换行
使用单一换行符来隔离块级内容,例如标题、列表、图片、代码块以及其他元素。 这里的例外是二级标题,必须有两个换行符。 二级标题紧随一级标题(或标题),中间没有段落或文字。
两行的留白有助于在代码编辑器中查看整个内容的结构组织。
标题
访问文档的读者可能会使用屏幕抓取程序或者其他辅助技术。 屏幕抓取器是一种线性输出设备, 它们每次输出页面上的一个条目。 如果页面上内容过多,你可以使用标题来为页面组织结构。 页面的良好结构对所有读者都有帮助,使得他们更容易浏览或者过滤感兴趣的内容。
可以 | 不可以 |
---|---|
更新页面或博客在前言部分中的标题 | 使用一级标题。因为 Hugo 会自动将页面前言部分的标题转化为一级标题。 |
使用编号的标题以便内容组织有一个更有意义的结构。 | 使用四级到六级标题,除非非常有必要这样。如果你要编写的内容有非常多细节,可以尝试拆分成多个不同页面。 |
在非博客内容页面中使用井号(# ) | 使用下划线 --- 或 === 来标记一级标题。 |
使用正常大小写来标示标题。例如:Extend kubectl with plugins | 使用首字母大写来标示标题。例如:Extend Kubectl With Plugins |
段落
可以 | 不可以 |
---|---|
尝试不要让段落超出 6 句话。 | 用空格来缩进第一段。例如,⋅⋅⋅段落前面的三个空格会将其缩进。 |
使用三个连字符(--- )来创建水平线。使用水平线来分隔段落内容。例如,在故事中切换场景或者在上下文中切换主题。 | 使用水平线来装饰页面。 |
链接
可以 | 不可以 |
---|---|
插入超级链接时给出它们所链接到的目标内容的上下文。例如:你的机器上某些端口处于开放状态。参见检查所需端口了解更详细信息。 | 使用有二义性的术语,如“点击这里”。例如:你的机器上某些端口处于打开状态。参见这里了解详细信息。 |
编写 Markdown 风格的链接:[链接文本](URL) 。例如:[Hugo 短代码](/zh/docs/contribute/style/hugo-shortcodes/#table-captions) ,输出是Hugo 短代码. | 编写 HTML 风格的超级链接:<a href="/media/examples/link-element-example.css" target="_blank">访问我们的教程!</a> ,或者创建会打开新 Tab 页或新窗口的链接。例如:[网站示例](https://example.com){target="_blank"} 。 |
列表
将一组相互关联的内容组织到一个列表中,以便表达这些条目彼此之间有先后顺序或者某种相互关联关系。 当屏幕抓取器遇到列表时,无论该列表是否有序,它会告知用户存在一组枚举的条目。 用户可以使用箭头键来上下移动,浏览列表中条目。 网站导航链接也可以标记成列表条目,因为说到底他们也是一组相互关联的链接而已。
如果列表中一个或者多个条目是完整的句子,则在每个条目末尾添加句号。 出于一致性考虑,一般要么所有条目要么没有条目是完整句子。
说明: 编号列表如果是不完整的介绍性句子的一部分,可以全部用小写字母,并按照 每个条目都是句子的一部分来看待和处理。
在编号列表中,使用数字一(
1.
)对非排序列表,使用加号(
+
)、星号(*
)、或者减号(-
)在每个列表之后留一个空行
对于嵌套的列表,相对缩进四个空格(例如,⋅⋅⋅⋅)。
列表条目可能包含多个段落。每个后续段落都要缩进或者四个空格或者一个制表符。
表格
数据表格的语义用途是呈现表格化的数据。 用户可以快速浏览表格,但屏幕抓取器需要逐行地处理数据。 表格标题可以用来给数据表提供一个描述性的标题。 辅助技术使用 HTML 表格标题元素来在页面结构中辨识表格内容。
- 请 Hugo 短代码 为表格添加标题。
内容最佳实践
本节包含一些建议的最佳实践,用来开发清晰、明确一致的文档内容。
使用现在时态
可以 | 不可以 |
---|---|
此命令启动代理。 | 此命令将启动一个代理。 |
例外:如果需要使用过去时或将来时来表达正确含义时,是可以使用的。
使用主动语态
可以 | 不可以 |
---|---|
你可以使用浏览器来浏览 API。 | API 可以被使用浏览器来浏览。 |
YAML 文件给出副本个数。 | 副本个数是在 YAML 文件中给出的。 |
例外:如果主动语态会导致句子很难构造时,可以使用被动语态。
使用简单直接的语言
使用简单直接的语言。避免不必要的短语,例如说“请”。
可以 | 不可以 |
---|---|
要创建 ReplicaSet,... | 如果你想要创建 ReplicaSet,... |
参看配置文件。 | 请自行查看配置文件。 |
查看 Pods。 | 使用下面的命令,我们将会看到 Pods。 |
将读者称为“你”
可以 | 不可以 |
---|---|
你可以通过 ... 创建一个 Deployment。 | 通过...我们将创建一个 Deployment。 |
在前面的输出中,你可以看到... | 在前面的输出中,我们可以看到... |
避免拉丁短语
尽可能使用英语而不是拉丁语缩写。
可以 | 不可以 |
---|---|
例如,... | e.g., ... |
也就是说,... | i.e., ... |
例外:使用 etc. 表示等等。
应避免的模式
避免使用“我们”
在句子中使用“我们”会让人感到困惑,因为读者可能不知道这里的 “我们”指的是谁。
可以 | 不可以 |
---|---|
版本 1.4 包含了 ... | 在 1.4 版本中,我们添加了 ... |
Kubernetes 为 ... 提供了一项新功能。 | 我们提供了一项新功能... |
本页面教你如何使用 Pods。 | 在本页中,我们将会学到如何使用 Pods。 |
避免使用俚语或行话
对某些读者而言,英语是其外语。 避免使用一些俚语或行话有助于他们更方便的理解内容。
可以 | 不可以 |
---|---|
Internally, ... | Under the hood, ... |
Create a new cluster. | Turn up a new cluster. |
避免关于将来的陈述
要避免对将来作出承诺或暗示。如果你需要讨论的是 Alpha 功能特性,可以将相关文字 放在一个单独的标题下,标示为 alpha 版本信息。
避免使用很快就会过时的表达
避免使用一些很快就会过时的陈述,例如“目前”、“新的”。 今天而言是新的功能,过了几个月之后就不再是新的了。
可以 | 不可以 |
---|---|
在版本 1.4 中,... | 在当前版本中,... |
联邦功能特性提供 ... | 新的联邦功能特性提供 ... |