用 reStructuredText 编写带真实示例的技术文档，并构建检查

## 讲清读者需要的内容，深层细节交给代码 面向需要理解并使用所述行为的读者写作。尽可能清晰、简洁地解释概念。底层细节有助于读者做出判断时可以纳入，但非常深入的实现内部机制应留给源代码说明。 - 只有当方法签名对正确使用该方法至关重要时，才详细说明签名。 - 只记录影响主要工作流程的命令参数和选项，不要罗列所有可用开关。 - 如果代码中的消息已经清楚说明原因和解决办法，不要再次解释相同的错误或异常。 - 与其提供穷尽式目录，不如优先给出聚焦的解释、真实的示例以及相关详情链接。 ## 根据变更类型和发布信息选择分支 绝不要硬编码维护版本列表。选择目标分支前，应读取项目的权威发布元数据，然后始终按照变更类型规则处理。 - 错误修复应提交到包含该错误的最早维护分支。 - 新功能文档应提交到引入该功能的分支。如果该分支已停止维护，则使用其后的下一个维护分支。 - 拼写修正、改写、结构调整和其他非功能变更应提交到最早维护分支。 - 独立进行版本管理的子项目文档遵循其自行声明的政策；如果政策有明确要求，包括新功能在内的所有变更都应提交到最早维护分支。 记录变更类型以及做出判断时使用的维护数据。如果无法获取发布元数据，或其含义不明确，不要猜测目标分支。 ## 统一标题符号和换行长度 各级标题应始终使用一致的下划线字符：1级使用等号，2级使用连字符，3级使用波浪号，4级使用句点，5级使用双引号。每条下划线必须覆盖标题文本的完整长度。仓库如为特定路径声明了标题例外，应采用该例外。 正文按80个字符换行；表格、URL和孤立行在换行会降低可读性时可以例外。列表项目符号必须位于行首。不要让粗体或斜体标记跨越多行。 行内代码使用成对的双反引号。对于使用默认语言的代码示例，采用简洁的双冒号形式，但标记会单独占一行时除外。需要指定语言或渲染上下文时，使用明确的 code-block 指令。 ## 统一指令的缩进和链接写法 指令内容缩进4个空格。双冒号标记之后，在内容之前留一个空行；每条指令前后也都要留空行。多行列表项的续行应与该项正文的起始位置对齐。 根据消息含义选择标准 admonition：note、tip、warning、caution 或 seealso。新增版本和弃用内容应分别使用专用指令，并附上相关版本和简短说明。 内部文档链接使用绝对文档路径。链接到特定小节时，使用带标签的交叉引用。绝不要使用相对内部路径。 对于外部站点，不要在正文中嵌入内联URL，而应把命名链接目标放在文件末尾。语言API中的类、方法、函数和内置类型应使用文档系统提供的专用角色。 ## YAML、XML 等配置示例始终按同一顺序排列 当功能支持多种配置格式时，应在 configuration-block 指令中展示所有受支持的格式。整个仓库采用统一顺序，让读者无需为每个页面重新理解布局即可进行比较。 - 服务和一般配置按 YAML、XML、编程语言格式的顺序展示。 - 路由、验证和对象映射按属性、YAML、XML、编程语言格式的顺序展示。 - 翻译资源按 XML、YAML、编程语言格式的顺序展示。 普通选项卡只用于非配置的并列内容，例如替代工具或工作流程。如果框架集成应用与独立应用的示例不同，应使用不同的语言标识符，让渲染器和读者能够区分上下文。 ## 用真实的名称和文件名注释编写代码示例 遵循目标语言的编码标准和项目已有的最佳实践。使用真实的名称和场景，不要使用掩盖意图的占位词。采用保留的示例域名和仓库约定的示例供应商名称。 - 在可行的情况下，代码块每行按85个字符换行。 - 包括 YAML 在内的示例都使用4个空格缩进。 - 如果命名空间和 import 声明有助于运行示例或理解类型，应将其纳入示例。 - 代码块开头使用注释标明文件名；除非下一行也是注释，否则不要在其后添加空行。 - 每条 shell 命令前都加上提示符标记。 - 折叠省略的代码块时，使用符合该语言的注释形式。 - 缩短同一行中某个值的一部分时，只使用省略号，不要添加注释标记。 - 遵守格式特有的空格规则，包括必要时 YAML 行内映射内部的空格。 示例应讲清受支持的用法，不应伪装成完整的生产实现。不要省略会导致所示代码运行失败的前提条件。 ## 使用浅显的美式英语，避免 simply 之类的词 使用美式英语写作。小节标题采用标题式大小写：首词、末词和主要词的首字母大写；简短功能词除非位于标题开头，否则使用小写。 用“you”指代读者，不要以“we”代表作者。使用不限定性别的代词。优先采用主动语态、基础词汇和直接句式，使世界各地的读者都能理解。可以使用缩写形式。 不要使用牛津逗号。避免使用习语，以及“obviously”“simply”“just”“easy”“clearly”“trivial”“of course”等带有轻视意味的词。这些词可能掩盖解释不足并使读者感到受挫。 每张图片都需要简洁的替代文本，并以大写字母开头、句点结尾。不要以“A screenshot of”或“Diagram of”开头。复杂图示应在周围正文中解释，不要把所有细节都塞入替代文本。 ## 完成前在本地构建文档，检查警告和失效链接 目录名末尾带斜杠，文件扩展名前带句点。在目录树示例中使用 `your-project/` 等中立的示例项目根目录。正文和示例中的文件名、路径、命令及引用目标必须保持一致。 将文档变更视为完成之前，应执行以下步骤： 1. 在指定的构建工作区中安装文档构建依赖项。 2. 运行仓库规定的构建命令。 3. 需要目视检查时，临时提供生成结果以供查看。 4. 检查变更页面中的警告、断开的引用、格式错误的指令、代码渲染、标题层级和图片说明。 5. 确认所选目标分支仍然符合变更类型和当前维护元数据。 如果仓库提供文档构建方式，不要仅凭查看源文件就报告成功。