Эта страница переведена с помощью Cloud Translation API.

Руководство по стилю документации TensorFlow

Передовые методы

Сосредоточьтесь на намерениях пользователя и целевой аудитории.
Используйте повседневные слова и делайте короткие предложения.
Используйте единообразную структуру предложений, формулировки и заглавные буквы.
Используйте заголовки и списки, чтобы упростить быстрое чтение документов.
Руководство по стилю Google Developer Docs очень полезно.

Маркдаун

За некоторыми исключениями, TensorFlow использует синтаксис Markdown, аналогичный GitHub Flavored Markdown (GFM). В этом разделе объясняются различия между синтаксисом Markdown GFM и Markdown, используемым для документации TensorFlow.

Напишите о коде

Встроенные упоминания кода

При использовании следующих символов в тексте заключайте `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
```

Ссылки в формате Markdown и блокнотах

Ссылки между файлами в репозитории

Используйте относительные ссылки между файлами в одном репозитории GitHub. Укажите расширение файла.

Например, файл, который вы сейчас читаете, находится в репозитории https://github.com/tensorflow/docs . Поэтому для ссылок на другие файлы в том же репозитории можно использовать относительные пути, как показано ниже:

[Basics](../../guide/basics.ipynb) создает Основы .

Это предпочтительный подход, поскольку таким образом работают ссылки на tensorflow.org , GitHub и Colab . Кроме того, пользователь остается на том же сайте, когда переходит по ссылке.

Внешние ссылки

Для ссылок на файлы, отсутствующие в текущем репозитории, используйте стандартные ссылки Markdown с полным URI. Предпочтительно указывать URI tensorflow.org , если он доступен.

Для ссылки на исходный код используйте ссылку, начинающуюся с https://www.github.com/tensorflow/tensorflow/blob/master/ , за которой следует имя файла, начинающееся с корневого каталога GitHub.

При создании ссылки на tensorflow.org добавьте кавычки `` в ссылку Markdown, чтобы отображался символ «внешняя ссылка».

[GitHub](https://github.com/tensorflow/docs) создает GitHub

Не включайте параметры запроса URI в ссылку:

Используйте: https://www.tensorflow.org/guide/data
Нет: https://www.tensorflow.org/guide/data?hl=en

Изображения

Рекомендации в предыдущем разделе касаются ссылок на страницы. Обработка изображений осуществляется иначе.

Как правило, не следует добавлять образы в репозиторий, а вместо этого следует добавить команду TensorFlow-Docs в свой запрос на слияние и попросить их разместить образы на tensorflow.org . Это поможет уменьшить размер вашего репозитория.

Если вы загружаете изображения в свой репозиторий, обратите внимание, что некоторые системы не обрабатывают относительные пути к изображениям. Лучше использовать полный URL-адрес, указывающий на конечное местоположение изображения на tensorflow.org .

Ссылки на документацию API

Ссылки на API преобразуются при публикации сайта. Чтобы сослаться на страницу справочника API символа, заключите путь к символу в обратные кавычки:

`tf.data.Dataset` создает tf.data.Dataset

Полные пути предпочтительнее, за исключением длинных. Пути можно сократить, отбросив начальные компоненты. Частичные пути будут преобразованы в ссылки, если:

На пути есть как минимум одна . , и
Этот частичный маршрут является уникальным в рамках проекта.

Пути к API указаны для каждого проекта , в котором опубликован Python API на tensorflow.org . Вы можете легко создать ссылки на несколько подпроектов из одного файла, заключив имена API в обратные кавычки. Например:

`tf.metrics` , `tf_agents.metrics` , `text.metrics` выдает: tf.metrics , tf_agents.metrics , text.metrics .

Для символов с несколькими псевдонимами путей предпочтение отдается пути, соответствующему странице API на tensorflow.org . Все псевдонимы будут перенаправлять на правильную страницу.

Математические вычисления в Markdown

Вы можете использовать MathJax в TensorFlow при редактировании файлов Markdown, но обратите внимание на следующее:

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 Docs или другое программное обеспечение для работы с документами, чтобы провести более тщательную проверку орфографии и грамматики.
Используйте непринужденный и дружелюбный тон. Пишите документацию по TensorFlow как беседу — как будто вы разговариваете с другим человеком один на один. Используйте поддерживающий тон в статье.

Избегайте оговорок, субъективных мнений и оценочных суждений. Слова вроде «легко», «просто» и «несложно» полны предположений. Что-то может казаться вам легким, но быть сложным для другого человека. Старайтесь избегать подобных выражений, когда это возможно.
Используйте простые, лаконичные предложения без сложной терминологии. Сложноподчиненные предложения, цепочки придаточных предложений и идиомы, характерные для конкретного места, могут затруднить понимание и перевод текста. Если предложение можно разделить на две части, это, вероятно, следует сделать. Избегайте точек с запятой. Используйте маркированные списки, когда это уместно.
Предоставьте контекст. Не используйте сокращения без объяснения. Не упоминайте проекты, не связанные с TensorFlow, без указания ссылок на них. Объясните, почему код написан именно так.

Руководство по использованию

Опы

В файлах Markdown используйте # ⇒ вместо одного знака равенства, если хотите показать, что возвращает операция.

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

В блокнотах отображайте результат вместо добавления комментария (если последнее выражение в ячейке блокнота не присвоено переменной, оно отображается автоматически).

В справочной документации API рекомендуется использовать doctest для отображения результатов.

Тензоры

Когда речь идёт о тензоре в целом, слово «тензор» не следует писать с заглавной буквы. Если же речь идёт о конкретном объекте, который передаётся в операцию или возвращается ею, то слово «тензор» следует писать с заглавной буквы и заключать в обратные кавычки, поскольку вы говорите именно об объекте Tensor .

Не используйте слово «тензоры» (во множественном числе) для описания множества объектов Tensor , если вы на самом деле не говорите об одном объекте Tensors . Вместо этого используйте выражение «список (или коллекция) объектов Tensor ».

Используйте словосочетание « форма» для описания осей тензора и укажите форму в квадратных скобках с обратными кавычками. Например:


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 следует отдавать предпочтение терминам «ось» или «индекс», а не «размерность». В противном случае легко спутать «размерность» с размерностью векторного пространства. «Трехмерный вектор» имеет одну ось длиной 3.