TensorFlow 文档风格指南：面向 `tensorflow/docs` 仓库的可维护写作规范-开发者社区

文档
开发工具
教程

【免费下载链接】docs

TensorFlow documentation

项目地址：https://gitcode.com/gh_mirrors/doc/docs

本篇技术指南以 TensorFlow 官方文档仓库gh_mirrors/doc/docs中的 docs_style.md 为骨架，系统讲解 TensorFlow 文档在 Markdown 语法、代码呈现、链接规范、行文风格与术语使用上的全部约定。读完本文，你将掌握撰写一份既能通过仓库内置nblint/nbfmt工具链检查、又能在 tensorflow.org 与 GitHub 上正确渲染的 TensorFlow 技术文档的完整实操方案。

为什么 TensorFlow 需要一份文档风格指南

TensorFlow 的叙事型文档（guides 与 tutorials）以 Markdown 文件和 Jupyter 笔记本两种形态存在于仓库中，并被同时发布到 tensorflow.org 与 GitHub 两个平台。同一份源码要跨平台渲染、被搜索引擎与自动化工具反复解析，就必须在格式与措辞上保持高度一致。风格指南的存在意义有三层：

面向读者：聚焦用户意图与受众，用日常词汇、短句与一致的句式/大小写，让文档更容易扫描和理解；
面向维护者：统一的标题层级与列表用法降低了多人协作的审阅成本，也让机器可读的 lint 规则得以落地；
面向工具链：仓库自带的 nblint 风格检查器正是对风格规则的"非穷尽式实现"——其模块 docstring 明确声明：这些 lint 断言实现了 TensorFlow 文档与风格指南中的部分规则（见 tensorflow.py）。

基础最佳实践可概括为五条：以用户意图和受众为中心；使用日常词汇并保持句子简短；保持句式、措辞与大小写一致；善用标题和列表提升可扫读性；参考 Google 开发者文档风格指南作为写作蓝本。

Markdown 语法约定：与 GitHub Flavored Markdown 的差异

TensorFlow 文档使用的 Markdown 语法与 GitHub Flavored Markdown（GFM）大体一致，但存在若干关键差异。掌握这些差异是正确贡献文档的第一步，因为同一份源文件最终要在 tensorflow.org、GitHub 与 Colab 三个环境同时渲染。

代码的行内提及

在正文中提及以下符号时，必须用反引号包裹：

参数名：`input`、`x`、`tensor`
返回张量名：`output`、`idx`、`out`
数据类型：`int32`、`float`、`uint8`
正文中引用的其他算子名：`list_diff()`、`shuffle()`
类名：`tf.Tensor`、`Strategy`
文件名：`image_ops.py`、`/path_to_dir/file_name`
数学表达式或条件：`-1-input.dims() <= dim <= input.dims()`

这种统一约定不仅利于阅读，也为后续 API 链接自动转换（见下文"API 文档链接"一节）提供了识别基础。

代码块

代码块使用三个反引号开头和结尾，并可在首个反引号组之后指定编程语言：

```python # some python code here ```

指定语言后，tensorflow.org 与 GitHub 都能提供正确的语法高亮。

仓库内文件之间的链接

同一仓库内文件的链接必须使用相对路径，并包含文件扩展名。例如，从本文档（位于site/en/community/contribute/）链接到指南页面的写法为：

\[Basics\]$../../guide/basics.ipynb$，即[Basics](https://link.gitcode.com/i/0c5c35b73cd0ea1868208027f027a02c)，对应仓库中的实际文件为 site/en/guide/basics.ipynb。

这是首选做法，因为这样 tensorflow.org、GitHub 和 Colab 上的链接全部可用，且读者点击链接后仍停留在同一站点。链接中必须保留.ipynb或.md扩展名——它在 tensorflow.org 上渲染时会自动去掉扩展名，但源文件里必须写全。

注意：本文档内部相对链接的正确写法应始终以仓库根目录为锚点，例如[docs.md](https://link.gitcode.com/i/4f6e782578c903d6aa51545d6c3e937f)、[docs_ref.md](https://link.gitcode.com/i/89a8e65519576dbed944d1c01f7b5030)，避免局部相对路径导致 404。

外部链接

对当前仓库之外的文件，使用带完整 URI 的标准 Markdown 链接，并优先链接到 tensorflow.org 的 URI。链接到源码时，URI 应以https://www.github.com/tensorflow/tensorflow/blob/master/开头，后接从 GitHub 根目录开始的文件名。链接离开 tensorflow.org 时，应在链接上加外部标记以便显示"外部链接"符号。

不要在链接中附带 URI 查询参数：

正确：https://www.tensorflow.org/guide/data
错误：https://www.tensorflow.org/guide/data?hl=en

图片的处理原则

图片与页面链接的处理方式不同。原则上不应当把图片直接提交进仓库，而是在提交 PR 时邀请 TensorFlow 文档团队将图片托管到 tensorflow.org，以避免仓库体积膨胀。如果确实需要随仓库提交图片，要注意部分系统不支持图片的相对路径，应优先使用指向图片在 tensorflow.org 上最终位置的完整 URL。

指向 API 文档的链接

API 链接在站点发布时会被自动转换：只需用反引号包裹符号路径即可链接到该符号的 API 参考页，例如`tf.data.Dataset`会在发布时转换为tf.data.Dataset的 API 页面链接。

路径可以使用简写（去掉前导路径组件），只要满足两个条件即可被转换：

路径中至少包含一个.；
该部分路径在项目中唯一。

API 链接对每一个在 tensorflow.org 上发布了 Python API 的项目都生效，因此在单个文件中可以轻松地同时链接多个子项目：

`tf.metrics`、`tf_agents.metrics`、`text.metrics`分别生成tf.metrics、tf_agents.metrics、text.metrics的链接。

对于存在多个路径别名的符号，略微倾向于使用与 tensorflow.org API 页面一致的路径；所有别名都会重定向到正确的页面。

Markdown 中的数学公式

TensorFlow 文档允许在 Markdown 文件中使用 MathJax，但必须注意其平台差异：

MathJax 在 tensorflow.org 上渲染正常；
MathJax 在 GitHub 上无法正确渲染；
数学记号可能让不熟悉的开发者感到困惑；
为保持一致，tensorflow.org 遵循与 Jupyter/Colab 相同的规则。

块级公式用$$包裹：

$$ E=\frac{1}{2n}\sum_x\lVert (y(x)-y'(x)) \rVert^2 $$

行内公式用 $ ... $ 包裹：

This is an example of an inline MathJax expression: $ 2 \times 2 = 4 $

$ ... $分隔符也可用于行内公式，但$形式通常更易读。如果需要在正文或 MathJax 表达式中使用美元符号本身，必须用前导反斜杠转义为\$；而代码块（如 Bash 变量）中的美元符号无需转义。

行文风格（Prose Style）

如果你要撰写或编辑大量叙事性文档，应先通读 Google 开发者文档风格指南。本仓库的指南进一步提炼出以下写作原则：

良好风格的若干原则

检查拼写与语法：大多数编辑器自带拼写检查器或相关插件，也可以把文本粘贴到文档软件中进行更全面的检查。
使用轻松友好的语气：写 TensorFlow 文档应像一对一对话那样自然，全文保持支持性的语气。

注意：语气不那么正式，不等于技术含量降低。要简化的是措辞，而不是技术内容。

避免免责声明、观点与价值判断："easily"、"just"、"simple" 这类词都暗含了预设——对你来说简单的东西，对别人可能很难，应尽量避免。
使用简洁、直击要害的句子，避免复杂术语：复合句、从句链和带有地域色彩的习语都会让文本难以理解和翻译。一个句子如果能拆成两句，就应当拆开。尽量避免使用分号，适当时使用项目符号列表。
提供上下文：不要使用未解释的缩写；提及非 TensorFlow 项目时必须给出链接；要解释代码为什么这样写。

用法指南（Usage Guide）

算子（Ops）的写法

在 Markdown 文件中，当需要展示算子的返回值时，使用# ⇒而不是单个等号：

# 'input' is a tensor of shape [2, 3, 5] tf.expand_dims(input, 0) # ⇒ [1, 2, 3, 5]

在笔记本（notebook）中，则直接展示运行结果而不是加注释——如果 notebook 单元格中最后一个表达式没有赋值给变量，它会被自动显示。而在 API 参考文档中，更推荐使用 doctest 来展示结果：以>>>前缀的可执行 Python 代码块会被自动测试，例如tf.concat的 docstring 示例，从而确保文档中的代码示例真实可运行。

张量（Tensors）的术语与大小写

关于tensor的措辞有一套严格的约定：

泛泛谈论张量时，不要大写"tensor"这个词；
当谈论一个由算子提供或返回的具体对象时，应当大写为Tensor并加上反引号，因为此时指的是Tensor对象本身；
不要用复数 "Tensors" 来描述多个Tensor对象（除非你真的在谈论一个Tensors对象），而应该说"a list (or collection) ofTensorobjects"；
使用shape一词来描述张量的轴，并用反引号包裹的方括号展示形状。

例如：

If `input` is a three-axis `Tensor` with shape `[3, 4, 3]`, this operation returns a three-axis `Tensor` with shape `[6, 8, 6]`.

如上例所示，描述Tensor形状的元素时，优先使用 "axis"（轴）或 "index"（索引）而不是 "dimension"（维度），否则容易与向量空间的"维度"概念混淆——一个"三维向量"只有单个长度为 3 的轴。

让风格指南落地：仓库中的自动化工具链

风格指南不是一次性人工审阅的清单，TensorFlow 文档仓库为其配套了一整套可执行的工具，让风格约束在 CI 中自动生效：

nblint（笔记本风格检查）：__main__.py提供命令行入口，Linter类（见 linter.py）负责按 scope（文件级/单元格级）与条件（any/all）调度所有 lint 断言，并汇总LinterStatus报告。tensorflow 风格模块除版权与许可证检查外，还验证笔记本中的 Colab/GitHub/Download/Website/TFHub 等按钮 URL 是否与文件路径匹配（见 tensorflow.py）。
nbfmt（笔记本格式化）：__main__.py统一笔记本 JSON 的缩进、元数据与单元格结构，支持--remove_outputs移除输出单元格、--test在 CI 中校验格式是否达标（见 nbfmt/main.py）。其 notebook_utils.py 负责加载与解析 notebook JSON。
templates：tools/templates/下提供了 notebook.ipynb 等官方模板，新笔记本应以此为基础创建，从源头上满足版权、许可证与按钮等硬性规范。

总结

TensorFlow 文档风格指南的核心，是在"跨平台渲染一致"与"机器可读可测试"两个目标之间建立一套明确的写作约定：Markdown 层面统一代码提及、相对链接、图片托管与 API 链接转换规则；行文层面统一语气、句式与术语大小写（tensor与Tensor的区分、axis 优先于 dimension、# ⇒展示算子结果）。而 nblint 与 nbfmt 工具链则将其中可自动化的规则固化为程序化检查，让每一位贡献者在提交 PR 前就能验证自己的文档是否符合规范。无论是撰写新的教程、修改现有指南，还是为 API docstring 补充 doctest 示例，本文列出的约定与工具都是你进入 TensorFlow 文档贡献流程的通行证。