Cilium 文档写作规范深度解析docsstyle.rst 背后的 reStructuredText 与 Sphinx 实践【免费下载链接】ciliumeBPF-based Networking, Security, and Observability项目地址: https://gitcode.com/GitHub_Trending/ci/cilium本篇技术指南基于 Cilium 官方文档风格指南 docsstyle.rst系统讲解贡献 Cilium 文档时应遵循的 reStructuredTextRST与 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_filterscilium_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 对象交互时使用 UpperCamelCasePascal 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_VERSIONlatest映射为HEADstable映射为当前版本号其他值视为具体 tag。这正是parsed-literal的作用场景——它告诉 Sphinx 在块内解析 RST 标记并执行替换使 URL 始终指向与当前文档版本匹配的分支或 tag。5.2 非代码的逐字输出用字面块::如果内容不是代码片段只是需要原样打印的片段例如 shell 命令的非结构化输出应使用字面块literal block标记::See the output in dmesg: :: [ 3389.935842] flen6 proglen70 pass3 imageffffffffa0069c8f fromtcpdump pid20583 [ 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-sessionbash可以使用但应仅限于真正的 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/目录。规范推荐的完整写作模式为四步向用户描述用何种配置可以完成某任务使用literalinclude引入真实文件内容解释配置含义包括关键设置的意义提供一条用户可直接复制粘贴、用于应用该配置的命令。仓库中大量文档正是这一模式的落地例如 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 中的本地预览流程与之互为配套先保证文档中每条命令可独立、顺序执行再保证本地渲染无误。七、链接、列表与 Callout7.1 链接优先块级超链接目标避免使用内嵌 URIembedded URI即... ...__把 URL 直接写在句中的写法因为它会显著降低 RST 源码的可读性应优先使用块级超链接目标block-level hyperlink targetURL 写在段落下方、不直接出现在句内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-issueCilium 定义了引用 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.避免 Well 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 中的规则放回仓库上下文可以看到每条写作约定都有构建侧的对应实现写作规则仓库侧支撑\|SCM_WEB\|版本感知 URLconf.py 的rst_epilog按READTHEDOCS_VERSION注入替换定义:gh-issue:专用角色conf.py 的extlinks字典注册parsed-literal渲染样式Documentation/_static/parsed-literal.css 提供专门样式shell-session Copy commands 按钮Documentation/_static/copybutton.js 与 copybutton.cssliteralinclude引用真实配置examples/目录下的真实文件如 examples/kubernetes-dns/ 系列文档变更的验证闭环docstest.rst 的make render-docs/make test-docs流程从源码结构看这套机制使文档的版本一致性成为系统性保证URL 随分支/tag 自动变化、配置内容随examples/文件自动同步、格式错误在 CI 的make test-docs中暴露。对新贡献者而言遵循这份风格指南不仅是格式要求更是让文档正确接入上述构建链路的前提。【免费下载链接】ciliumeBPF-based Networking, Security, and Observability项目地址: https://gitcode.com/GitHub_Trending/ci/cilium创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 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 文档时应遵循的 reStructuredTextRST与 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_filterscilium_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 对象交互时使用 UpperCamelCasePascal 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_VERSIONlatest映射为HEADstable映射为当前版本号其他值视为具体 tag。这正是parsed-literal的作用场景——它告诉 Sphinx 在块内解析 RST 标记并执行替换使 URL 始终指向与当前文档版本匹配的分支或 tag。5.2 非代码的逐字输出用字面块::如果内容不是代码片段只是需要原样打印的片段例如 shell 命令的非结构化输出应使用字面块literal block标记::See the output in dmesg: :: [ 3389.935842] flen6 proglen70 pass3 imageffffffffa0069c8f fromtcpdump pid20583 [ 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-sessionbash可以使用但应仅限于真正的 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/目录。规范推荐的完整写作模式为四步向用户描述用何种配置可以完成某任务使用literalinclude引入真实文件内容解释配置含义包括关键设置的意义提供一条用户可直接复制粘贴、用于应用该配置的命令。仓库中大量文档正是这一模式的落地例如 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 中的本地预览流程与之互为配套先保证文档中每条命令可独立、顺序执行再保证本地渲染无误。七、链接、列表与 Callout7.1 链接优先块级超链接目标避免使用内嵌 URIembedded URI即... ...__把 URL 直接写在句中的写法因为它会显著降低 RST 源码的可读性应优先使用块级超链接目标block-level hyperlink targetURL 写在段落下方、不直接出现在句内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-issueCilium 定义了引用 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.避免 Well 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 中的规则放回仓库上下文可以看到每条写作约定都有构建侧的对应实现写作规则仓库侧支撑\|SCM_WEB\|版本感知 URLconf.py 的rst_epilog按READTHEDOCS_VERSION注入替换定义:gh-issue:专用角色conf.py 的extlinks字典注册parsed-literal渲染样式Documentation/_static/parsed-literal.css 提供专门样式shell-session Copy commands 按钮Documentation/_static/copybutton.js 与 copybutton.cssliteralinclude引用真实配置examples/目录下的真实文件如 examples/kubernetes-dns/ 系列文档变更的验证闭环docstest.rst 的make render-docs/make test-docs流程从源码结构看这套机制使文档的版本一致性成为系统性保证URL 随分支/tag 自动变化、配置内容随examples/文件自动同步、格式错误在 CI 的make test-docs中暴露。对新贡献者而言遵循这份风格指南不仅是格式要求更是让文档正确接入上述构建链路的前提。【免费下载链接】ciliumeBPF-based Networking, Security, and Observability项目地址: https://gitcode.com/GitHub_Trending/ci/cilium创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考