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

Лучшие практики

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

Уценка

За некоторыми исключениями, TensorFlow использует синтаксис Markdown, аналогичный GitHub Flavored Markdown (GFM). В этом разделе объясняются различия между синтаксисом GFM Markdown и 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 . Кроме того, читатель остается на том же сайте, когда нажимает ссылку.

Примечание. Для относительных ссылок необходимо указать расширение файла, например .ipynb или .md . Он будет отображаться на tensorflow.org без расширения.

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

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

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

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

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

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

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

Изображений

Совет в предыдущем разделе касается ссылок на страницы. Изображения обрабатываются по-разному.

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

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

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

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

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

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

• Есть хотя бы один . в пути и
• Частичный путь уникален в рамках проекта.

Пути API связаны для каждого проекта с API Python, опубликованным на 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 \)

Разделители \\( ... \\) также подходят для встроенных математических операций, но форма $ иногда более читабельна.

Примечание. Если вам нужно использовать знак доллара в тексте или выражениях MathJax, экранируйте его косой чертой: \$ . Знаки доллара внутри блоков кода (например, имена переменных Bash) экранировать не нужно.

Стиль прозы

Если вы собираетесь писать или редактировать значительную часть описательной документации, прочтите Руководство по стилю документации для разработчиков Google .

Принципы хорошего стиля

• Проверьте орфографию и грамматику в своих сообщениях. Большинство редакторов включают в себя функцию проверки орфографии или плагин для проверки орфографии. Вы также можете вставить свой текст в Google Doc или другое программное обеспечение для работы с документами для более надежной проверки орфографии и грамматики.
• Говорите непринужденным и дружелюбным голосом. Пишите документацию TensorFlow как беседу — как будто вы разговариваете с другим человеком один на один. Используйте в статье поддерживающий тон.

Примечание. Быть менее формальным не означает быть менее техническим. Упрощайте прозу, а не техническое содержание.

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

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

Операции

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

# '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.