Руководство по стилю документации 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
```

Используйте относительные ссылки между файлами в одном репозитории 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:

  • Используйте: <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 связаны для каждого проекта с API Python, опубликованным на tensorflow.org . Вы можете легко связать несколько подпроектов из одного файла, заключив имена API в обратные кавычки. Например:

Для символов с несколькими псевдонимами пути предпочтение отдается пути, который соответствует странице 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 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.