此页面由 Cloud Translation API 翻译。
Switch to English

TensorFlow文档样式指南

最佳实务

  • 关注用户意图和受众。
  • 使用日常用词,使句子简短。
  • 使用一致的句子结构,措辞和大写字母。
  • 使用标题和列表可以使文档更易于扫描。
  • Google开发者文档样式指南会有所帮助。

降价促销

除了少数例外,TensorFlow使用与GitHub Flavored Markdown (GFM)类似的Markdown语法。本节说明了GFM Markdown语法和TensorFlow文档所使用的Markdown之间的区别。

写代码

内联代码

在文本中使用`backticks` ,请将以下符号放在其周围:

  • 参数名称: `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()`

代码块

使用三个反引号来打开和关闭代码块。 (可选)在第一个反引号组之后指定编程语言,例如:


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

使用存储库中文件之间的相对链接。这适用于tensorflow.orgGitHub
[Custom layers](../tutorials/eager/custom_layers.ipynb)在网站上生成自定义图层

网站发布后会转换API链接。要链接到符号的API参考页面,请在反引号中包含完整的符号路径:

对于C ++ API,请使用名称空间路径:

对于外部链接,包括https://www.tensorflow.org上不在tensorflow/docs存储库中的tensorflow/docs ,请使用带有完整URI的标准Markdown链接。

要链接到源代码,请使用以https://www.github.com/tensorflow/tensorflow/blob/master/开头的链接,然后是从GitHub根开头的文件名。

此URI命名方案可确保https://www.tensorflow.org可以将链接转发到与您正在查看的文档版本相对应的代码分支。

链接中不要包含URI查询参数。

文件路径使用下划线表示空格,例如custom_layers.ipynb

在网站 GitHub上使用的链接中包含文件扩展名,例如,
[Custom layers](../tutorials/eager/custom_layers.ipynb)

Markdown中的数学

编辑Markdown文件时,可以在TensorFlow中使用MathJax,但请注意以下几点:

  • MathJax可在tensorflow.org上正确呈现。
  • MathJax无法在GitHub上正确呈现。
  • 对于不熟悉的开发人员而言,此表示可能会令人反感。
  • 为了保持一致性, tensorflow.org遵循与Jupyter / Colab相同的规则。

在一块MathJax周围使用$$

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

$ ... $包裹内联MathJax表达式:


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

这是一个内联MathJax表达式的示例:$ 2 \ times 2 = 4 $

\\( ... \\)分隔符也适用于内联数学,但是$格式有时更易读。

散文风格

如果您要编写或编辑叙述性文档的大部分内容,请阅读Google开发者文档样式指南

良好风格的原则

  • 检查文稿中的拼写和语法。大多数编辑器都包含拼写检查器或具有可用的拼写检查插件。您还可以将文本粘贴到Google文档或其他文档软件中,以进行更强大的拼写和语法检查。
  • 使用轻松友好的声音。像对话一样编写TensorFlow文档-就像您与其他人一对一交谈一样。在文章中使用辅助语气。
  • 避免免责声明,意见和价值判断。像“轻松”,“公正”和“简单”这样的词都带有假设。某些东西对您来说似乎很容易,但对另一个人来说却很难。尽可能避免这些情况。
  • 使用简单的句子,不要使用复杂的行话。复合句子,从句的链条和特定于位置的惯用语会使文本难以理解和翻译。如果一个句子可以一分为二,它应该可以。避免使用分号。适当时使用项目符号列表。
  • 提供上下文。不要在不解释的情况下使用缩写。不要在未链接的情况下提及非TensorFlow项目。解释为什么按原样编写代码。

使用指南

行动

要显示操作返回的内容时,请使用# ⇒而不是单个等号。

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

张量

一般而言,在谈论张量时,请不要将tensor一词大写。当您谈论提供给op或从op返回的特定对象时,您应该大写Tensor一词并在其周围加上反引号,因为您是在谈论Tensor对象。

除非您真的在谈论一个Tensors对象,否则不要使用Tensors (复数)一词来描述多个Tensor对象。相反,说“ Tensor对象的列表(或集合)”。

使用形状一词来详细说明张量的尺寸,并在带有反引号的方括号中显示该形状。例如:


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