Cilium 文档写作规范深度解析：docsstyle.rst 背后的 reStructuredText 与 Sphinx 实践

Cilium 文档写作规范深度解析：docsstyle.rst 背后的 reStructuredText 与 Sphinx 实践

【免费下载链接】ciliumeBPF-based Networking, Security, and Observability项目地址: https://gitcode.com/GitHub_Trending/ci/cilium

本篇技术指南基于 Cilium 官方文档风格指南 docsstyle.rst，系统讲解贡献 Cilium 文档时应遵循的 reStructuredText（RST）与 Sphinx 写作规范：从页面头部模板、标题大小写、代码块三种类型的正确选型，到literalinclude配置引用、模板变量替换、链接与列表格式，再到语言层面的常见陷阱与改写技巧。读完后，你将能够直接按该仓库的既有规范撰写可渲染、可维护、易本地化的文档，并理解每条规则背后由 conf.py 和静态资源支撑的具体机制。

一、规范的目标与适用范围

docsstyle.rst 是 Cilium 文档贡献指南（Documentation/contributing/docs/index.rst）中与文档结构、文档测试并列的核心章节之一。该指南明确列出了四个目标：

• 确保文档以最佳方式渲染，尤其是代码块；
• 让文档易于维护和扩展；
• 在整个文档体系中保持风格一致；
• 最终提升用户阅读体验，帮助其快速找到所需信息。

这些目标对应着三类可验证的工程手段：渲染层面的指令选型（code-block、literalinclude、parsed-literal等）、组织层面的模板约束（统一头部、examples/目录联动），以及语言层面的可本地化约束。配套的 docstest.rst 则给出了预览与验证流程：通过make render-docs启动cilium/docs-builder容器，在 http://localhost:9081/ 实时预览，提交前用make test-docs检查是否引入新的警告或错误。

二、通用约定：语言、连字符与行宽

2.1 使用美式英语并保持一致风格

规范第一条即要求文档统一使用美式英语（US English）。例如应写 "prioritize" 而不是 "prioritise"，写 "color" 而不是 "colour"。这一点与 conf.py 中language = "en"的设置以及拼写检查配置相呼应——仓库通过spelling_exclude_patterns排除生成文件、通过spelling_filters（cilium_spellfilters过滤器）定制拼写检查，对词形做统一约束。

同时要求：

• 尽量与文档其余部分（至少与被修改页面其余部分）保持风格一致；
• 能省略连字符就省略，例如写 "load balancing" 而非 "load-balancing"。

2.2 正文换行宽度

正文段落建议控制在约 80 字符宽度内换行。规范中没有硬性规定，但说明这一宽度在多数场景下是安全的默认值，有利于 diff 可读性和行内评论定位。

三、页面头部与标题格式

3.1 新文件的标准头部

向Documentation/新增文件时，规范要求使用如下头部（注意开头的only条件编译指令，使该警告仅出现在非 epub/latex/html 的直接源码视图场景）：

.. only:: not (epub or latex or html) WARNING: You are looking at unreleased Cilium documentation. Please use the official rendered version released here: https://docs.cilium.io

唯一的例外是会被其他文档文件作为片段（fragment）引用的 RST 文件，这类文件不需要该头部。这一点在 conf.py 中有对应机制：exclude_patterns中排除了operations/troubleshooting_clustermesh.rst，注释明确说明该文件"已作为其他页面的片段被包含，若参与源码处理会导致标签被重复处理"——这正是"片段文件"概念在构建配置中的直接体现。

3.2 标题使用句首大写（sentence case）

所有标题应优先使用 sentence case（仅首词首字母大写），而不是 title case（每个实词首字母大写）。这条规则降低了本地化难度，也与 Kubernetes 风格指南的默认做法对齐。

四、API 对象的大小写规则

对于 Kubernetes API 对象，规范引用了 Kubernetes 风格指南中"API 对象大小写"一节，并归纳为两条：

• 当你具体指代与某个 API 对象交互时，使用 UpperCamelCase（Pascal case）；
• 当你泛泛讨论某个 API 对象时，使用 sentence-style capitalization（句首大写形式）。

以 Gateway API 为例，"Gateway API" 始终大写；作为实体的 API 对象写作 "Gateway"，而指代某个具体实例时写作小写 "gateway"。规范给出了正误对照：

正确的写法：

- Gateway API is a subproject of Kubernetes SIG Network. - Cilium is conformant to the Gateway API spec at version X.Y.Z. - In order to expose this service, create a Gateway to hold the listener configuration. - Traffic from the Internet passes through the gateway to get to the backend service. - Now that you have created the "foo" gateway, you need to create some Routes.

错误的写法：

- The implementation of gateway API - To create a gateway object, ...

判断标准可以概括为：API 规范名称整体大写；对象作为"类型/实体"时首字母大写；作为"某个已创建的具体资源"时用小写普通名词。

五、代码块的三种类型及其选型

这是 docsstyle.rst 中最具技术含量的一节。文档中的字面内容块通常落在以下三类之一，选错指令会直接影响渲染结果或交互功能（例如 "Copy commands" 按钮的生成）。

5.1 含替换引用（substitution references）时用parsed-literal

当代码片段中需要嵌入|SCM_WEB|这类替换引用（substitution reference）时，必须使用.. parsed-literal::指令，否则 token 不会被替换。

推荐：

.. parsed-literal:: $ kubectl create -f \ |SCM_WEB|\/examples/minikube/http-sw-app.yaml

避免：

.. code-block:: shell-session $ kubectl create -f \ |SCM_WEB|\/examples/minikube/http-sw-app.yaml

|SCM_WEB|的机制在 conf.py 中定义：rst_epilog中注入.. |SCM_WEB| replace:: \{s}，其值由githubusercontent + branch拼接而成；branch来自环境变量READTHEDOCS_VERSION，latest映射为HEAD，stable映射为当前版本号，其他值视为具体 tag。这正是parsed-literal的作用场景——它告诉 Sphinx 在块内解析 RST 标记并执行替换，使 URL 始终指向与当前文档版本匹配的分支或 tag。

5.2 非代码的逐字输出用字面块::

如果内容不是代码片段，只是需要原样打印的片段（例如 shell 命令的非结构化输出），应使用字面块（literal block）标记::：

See the output in ``dmesg``: :: [ 3389.935842] flen=6 proglen=70 pass=3 image=ffffffffa0069c8f from=tcpdump pid=20583 [ 3389.935847] JIT code: 00000000: 55 48 89 e5 48 83 ec 60 48 89 5d f8 44 8b 4f 68 See more output in ``dmesg``:: [ 3389.935849] JIT code: 00000010: 44 2b 4f 6c 4c 8b 87 d8 00 00 00 be 0c 00 00 00

规范同时给出了避免项：这类内容不要用.. parsed-literal::包裹。原因是其中根本没有代码，也没有需要解析的 RST 标记——code-block会让 Sphinx 尝试做语法高亮，parsed-literal会让 Sphinx 在块内查找并解析 RST 标记，两者都是无谓的处理开销并可能引入意外行为。

5.3 真正的代码用code-block，且必须带语言名

内容含代码或结构化输出时，使用.. code-block::指令；不要使用.. code::指令，后者灵活性稍差。

.. code-block:: shell-session $ ls cilium $ cd cilium/

关于语言标识符的选型规则：

• code-block必须带语言名参数，例如.. code-block:: yaml或.. code-block:: shell-session；
• bash可以使用，但应仅限于真正的 Bash 脚本；
• 凡是 shell 命令列表——尤其是命令与其输出混合的片段——应使用shell-session，它能带来最佳的颜色区分，并可能触发 "Copy commands" 按钮的生成。

最后一点与渲染层实现相关：Documentation/_static/copybutton.js 与 copybutton.css 就是该按钮的前端实现，而shell-session语法中高亮的$/#提示符正是其识别可复制命令行的依据。

5.4 shell 命令的提示符约定

包含 shell 命令（尤其附带输出）的片段，命令前应使用提示符标记：普通用户命令用$，需要管理员权限的命令用#；也可以用sudo作为标记特权命令的替代方式。这一约定使读者无需判断权限边界，也支撑了上面的复制按钮机制。

六、配置文件写作：literalinclude与模板替换

这是指南中篇幅最实操的一节，核心思想是：文档中的配置内容不要手抄，直接引用仓库中的真实文件，以保证文档与代码不漂移（drift）。

6.1 避免 HEREDOC，使用literalinclude

文档中展示"创建某个文件"时，避免使用cat的 HEREDOC 语法内联内容，而应使用literalinclude指令引用仓库中实际存在的文件（通常位于examples/目录）。如果该文件在仓库中尚不存在，应先把文件加入examples/目录。

规范推荐的完整写作模式为四步：

1. 向用户描述用何种配置可以完成某任务；
2. 使用literalinclude引入真实文件内容；
3. 解释配置含义，包括关键设置的意义；
4. 提供一条用户可直接复制粘贴、用于应用该配置的命令。

仓库中大量文档正是这一模式的落地，例如 security/dns.rst 使用.. literalinclude:: ../../examples/kubernetes-dns/dns-pattern.yaml引用真实策略文件，gettingstarted/demo.rst 引用../../examples/minikube/sw_l3_l4_policy.yaml等。

参考示例（来自规范本身）：

To configure feature X, create a file with the following contents: .. literalinclude:: ../../examples/kubernetes/feature-x.yaml :language: yaml This configuration enables feature X by setting: - ``enableFeatureX: true``: Activates the feature - ``featureXMode: advanced``: Uses advanced mode for better performance Apply the configuration with: .. parsed-literal:: $ kubectl apply -f \ |SCM_WEB|\/examples/kubernetes/feature-x.yaml

注意其中两条细节：

• literalinclude用:language:参数声明高亮语言；
• 当命令引用仓库文件 URL 时，使用|SCM_WEB|替换引用，确保用户拿到的是与其所读文档版本（branch/tag）一致的文件，而非固定的 main 分支链接。

6.2 用户相关取值用.tmpl模板 +envsubst

对于需要用户特定值（集群名、ID、区域）的配置文件，不要让用户手工编辑文件，而应使用带变量替换的模板文件。做法是：模板文件存放在examples/目录、扩展名为.tmpl，并用envsubst完成变量替换。

规范给出的示例流程：

export NAME="$(whoami)-$RANDOM" curl -L \ |SCM_WEB|\/examples/kubernetes/eks-config.tmpl \ | envsubst > eks-config.yaml $ eksctl create cluster -f eks-config.yaml

该模式的价值，规范总结了四点：

• 维护者可以按顺序复制粘贴命令来复现用户问题；
• 变量受控生成而非手工键入，减少错误；
• 模板文件纳入版本控制，与文档保持同步；
• 失败是系统性的（模板问题），而非随机的（用户拼写错误）。

这一设计本质上服务于文档的"可复制粘贴测试"工作流——docstest.rst 中的本地预览流程与之互为配套：先保证文档中每条命令可独立、顺序执行，再保证本地渲染无误。

七、链接、列表与 Callout

7.1 链接：优先块级超链接目标

避免使用内嵌 URI（embedded URI，即... <...>`__把 URL 直接写在句中）的写法，因为它会显著降低 RST 源码的可读性；应优先使用块级超链接目标（block-level hyperlink target，URL 写在段落下方、不直接出现在句内）：

See the `documentation for Cilium`_. Here is another link to `the same documentation <cilium documentation>`_. .. _documentation for Cilium: .. _cilium documentation: https://docs.cilium.io/en/latest/

若确实必须使用内嵌 URI，则使用匿名超链接（双下划线结尾... <...>`__）而不是命名引用（单下划线结尾... <...>`_）。

7.2 列表的三条格式规则

• 缩进对齐：列表项正文应与首行文本（项目符号之后）左对齐：

- The text in this item wraps of several lines, with consistent indentation.

• 枚举列表用自动编号：优先#.自动编号，不要手工写1. 2. 3.：

#. First item #. Second item

• 句末标点一致性：bullet 列表项一般不加句点，除非各项都是完整句子；一旦某一项需要句点，则全部项都加。

7.3 Callout（如note）的正确使用边界

规范强调.. note::应用于"帮助读者在具体语境下理解的信息"，不要用它来逃避对段落的重构。典型反例：新增一个补全某功能的配置标志时，不必单独追加一个 note，因为它并不特别需要读者额外注意；正确做法是把新信息合并进现有段落。规范用一个"pod 闪烁"的类比段落演示了"追加 note"与"合并进段落"两种写法的差异：后者以"默认值是多少、用什么标志调整"的形式把信息织入上下文，而不是另起一块打断阅读流。

7.4 专用角色：gh-issue

Cilium 定义了引用 GitHub issue 的专用角色，文档中应统一使用：

See :gh-issue:`1234`.

而不是手工拼写完整 URL 的内嵌链接。该角色在 conf.py 的extlinks字典中注册：

extlinks = { 'git-tree': (scm_web + "/%s", None), 'github-backport': (backport_format, None), 'gh-issue': (github_repo + 'issues/%s', 'GitHub issue %s'), ... }

可见gh-issue会渲染为"GitHub issue 1234"并指向 issues 页面；同族的git-tree角色同样基于scm_web（版本感知的 raw 文件地址），是|SCM_WEB|替换引用的角色化替代，两者共同构成文档中"版本感知链接"的两套机制。

八、语言风格：常见陷阱与改写手法

指南的"Common pitfalls"一节以 Kubernetes 风格指南的"内容最佳实践"为默认基线，逐条给出 Cilium 文档 PR 中最常见的评审反馈。以下规则均配对照示例，可整体作为自查清单使用。

8.1 使用主动语态

推荐 "Enable the flag."，避免 "Ensure the flag is enabled."。

8.2 使用现在时

推荐 "The service returns a response code."，避免 "The service will return a response code."。

8.3 以 "you" 称呼读者，不用 "we"

推荐 "You can specify values to filter tags."，避免 "We'll specify this value to filter tags."。

8.4 使用朴素、直接的表达

推荐 "Always configure the bundle explicitly in production environments."，避免 "It is recommended to always configure the bundle explicitly in production environments."。

8.5 为本地化而写

默认假设内容会被机器翻译。修辞手法、习语（如 "above"、"below" 这类方位指代）往往难以本地化：

• 推荐 "The following example"、"To assist this process,"；
• 避免 "The example below"、"To give this process a boost,"。

8.6 缩写与拉丁缩略语

• 缩写词在页面首次出现时给出全称定义：推荐 "Certificate authority (CA)"，避免直接写 "CA"；
• 不使用拉丁缩略语：推荐 "For example,"、"In other words,"、"by following the ..."、"and others"；避免 "e.g."、"i.e."、"via"、"etc."；
• 完整拼出连接词：推荐 "and"，避免 "&"。

8.7 使用具体措辞，避免 "this" 与 "it"

规范给出了这一节两条理由：其一，间接语言对作者清晰度和读者理解力都假设过高；其二，具体语言更易于评审、更易于本地化。

"pods 刷漆"示例：

Feature A requires all pods to be painted blue. This means that the Agent must apply its "paint" action to all pods. To achieve this, use the dedicated CLI invocation.

其中 "this" 同时间接指代了一个推断出的后果（"this means"）和一个期望的目标状态（"to achieve this"）。改写为：

Feature A requires all pods to be painted blue. Consequently, the Agent must apply its "paint" action to all pods. To make the Agent paint all pods blue, use the dedicated CLI invocation.

同类示例：

• 推荐 "For each core, the Ingester attempts to spawn a worker pool."，避免 "For each core, it attempts to spawn a worker pool."；
• 推荐 "Set the annotation value to remote."，避免 "Set it to remote."。

九、规范落地的配套机制速览

把 docsstyle.rst 中的规则放回仓库上下文，可以看到每条"写作约定"都有构建侧的对应实现：

从源码结构看，这套机制使文档的"版本一致性"成为系统性保证：URL 随分支/tag 自动变化、配置内容随examples/文件自动同步、格式错误在 CI 的make test-docs中暴露。对新贡献者而言，遵循这份风格指南不仅是格式要求，更是让文档正确接入上述构建链路的前提。

【免费下载链接】ciliumeBPF-based Networking, Security, and Observability项目地址: https://gitcode.com/GitHub_Trending/ci/cilium