Внесите свой вклад в документацию API TensorFlow.

Тестируемые строки документации

TensorFlow использует DocTest для тестирования фрагментов кода в строках документации Python. Фрагмент должен представлять собой исполняемый код Python. Чтобы включить тестирование, добавьте к строке >>> (три левые угловые скобки). Например, вот отрывок из функции tf.concat в исходном файле array_ops.py :

def concat(values, axis, name="concat"):
  """Concatenates tensors along one dimension.
  ...

  >>> t1 = [[1, 2, 3], [4, 5, 6]]
  >>> t2 = [[7, 8, 9], [10, 11, 12]]
  >>> concat([t1, t2], 0)
  <tf.Tensor: shape=(4, 3), dtype=int32, numpy=
  array([[ 1,  2,  3],
         [ 4,  5,  6],
         [ 7,  8,  9],
         [10, 11, 12]], dtype=int32)>

  <... more description or code snippets ...>

  Args:
    values: A list of `tf.Tensor` objects or a single `tf.Tensor`.
    axis: 0-D `int32` `Tensor`.  Dimension along which to concatenate. Must be
      in the range `[-rank(values), rank(values))`. As in Python, indexing for
      axis is 0-based. Positive axis in the rage of `[0, rank(values))` refers
      to `axis`-th dimension. And negative axis refers to `axis +
      rank(values)`-th dimension.
    name: A name for the operation (optional).

    Returns:
      A `tf.Tensor` resulting from concatenation of the input tensors.
  """

  <code here>

Чтобы оценить качество справочной документации, см. раздел примеров рекомендаций TensorFlow 2 API Docs . (Имейте в виду, что средство отслеживания задач на этом листе больше не используется.)

Сделайте код тестируемым с помощью DocTest

В настоящее время во многих строках документации используются обратные кавычки (```) для идентификации кода. Чтобы сделать код доступным для тестирования с помощью DocTest:

  • Удалите обратные кавычки (```) и используйте левые скобки (>>>) перед каждой строкой. Используйте (...) перед продолжающимися строками.
  • Добавьте новую строку, чтобы отделить фрагменты DocTest от текста Markdown для правильной визуализации на tensorflow.org.

Настройки

TensorFlow использует несколько настроек встроенной логики doctest:

  • Он не сравнивает значения с плавающей запятой как текст: значения с плавающей запятой извлекаются из текста и сравниваются с использованием allclose с либеральными допусками atol и rtol . Это позволяет:
    • Более четкая документация. Авторам не нужно включать все десятичные знаки.
    • Более надежные тесты. Численные изменения в базовой реализации никогда не должны приводить к сбою документального теста.
  • Он проверяет вывод только в том случае, если автор включает вывод для строки. Это позволяет создавать более понятные документы, поскольку авторам обычно не нужно фиксировать ненужные промежуточные значения, чтобы предотвратить их печать.

Рекомендации по строке документации

  • В целом : цель doctest — предоставить документацию и подтвердить, что документация работает. Это отличается от модульного тестирования. Так:
    • Делайте примеры простыми.
    • Избегайте длинных или сложных результатов.
    • Если возможно, используйте круглые числа.
  • Формат вывода : вывод фрагмента должен находиться непосредственно под кодом, генерирующим вывод. Кроме того, выходные данные в строке документации должны быть точно такими же, как выходные данные после выполнения кода. См. приведенный выше пример. Также ознакомьтесь с этой частью документации DocTest. Если выходные данные превышают ограничение в 80 строк, вы можете поместить дополнительные выходные данные в новую строку, и DocTest распознает их. Например, см. многострочные блоки ниже.
  • Globals : модули `tf` , np и os всегда доступны в DocTest TensorFlow.

  • Использовать символы : в DocTest вы можете напрямую получить доступ к символам, определенным в том же файле. Чтобы использовать символ, который не определен в текущем файле, используйте общедоступный API TensorFlow tf.xxx вместо xxx . Как вы можете видеть в примере ниже, доступ к `random.normal` осуществляется через `tf.random.normal` . Это связано с тем, что `random.normal` не отображается в NewLayer .

    def NewLayer():
  """This layer does cool stuff.

  Example usage:

  >>> x = tf.random.normal((1, 28, 28, 3))
  >>> new_layer = NewLayer(x)
  >>> new_layer
  <tf.Tensor: shape=(1, 14, 14, 3), dtype=int32, numpy=...>
  """

  • Значения с плавающей запятой : документация TensorFlow извлекает значения с плавающей запятой из строк результатов и сравнивает их с помощью np.allclose с разумными допусками ( atol=1e-6 , rtol=1e-6 ). Таким образом, авторам не нужно беспокоиться о слишком точных строках документации, вызывающих сбои из-за числовых проблем. Просто вставьте ожидаемое значение.

  • Недетерминированный вывод : используйте многоточие ( ... ) для неопределенных частей, и DocTest проигнорирует эту подстроку.

    x = tf.random.normal((1,))
print(x)
    <tf.Tensor: shape=(1,), dtype=float32, numpy=..., dtype=float32)>

  • Многострочные блоки : DocTest строго определяет разницу между однострочными и многострочными инструкциями. Обратите внимание на использование (...) ниже:

    if x > 0:
  print("X is positive")
model.compile(
  loss="mse",
  optimizer="adam")

  • Исключения : сведения об исключении игнорируются, за исключением возникшего исключения. Смотрите это для более подробной информации.

    np_var = np.array([1, 2])
tf.keras.backend.is_keras_tensor(np_var)
    Traceback (most recent call last):

    ValueError: Unexpectedly found an instance of type `<class 'numpy.ndarray'>`.

Используйте локальную копию tf-doctest.

Некоторые API в TensorFlow взяты из внешнего проекта:

Если вы работаете над внешним проектом или над API-интерфейсами TensorFlow, размещенными во внешнем проекте, эти инструкции не будут работать, если у этого проекта нет собственной локальной копии tf_doctest и вы не используете эту копию вместо копии TensorFlow.

Например: tf_estimator_doctest.py .

Протестируйте на своей локальной машине

Есть два способа локально протестировать код в строке документации:

  • Если вы меняете только строку документации класса/функции/метода, вы можете проверить это, передав путь к этому файлу в tf_doctest.py . Например:

    python tf_doctest.py --file=<file_path>

    Это запустит его с использованием установленной вами версии TensorFlow. Чтобы быть уверенным, что вы используете тот же код, который тестируете:

    • Используйте обновленную версию tf-nightly pip install -U tf-nightly
    • Перебазируйте свой запрос на включение на недавнее получение из главной ветки TensorFlow .

  • Если вы меняете код и строку документации класса/функции/метода, вам нужно будет собрать TensorFlow из исходного кода . После того, как вы настроите сборку из исходного кода, вы можете запустить тесты:

    bazel run //tensorflow/tools/docs:tf_doctest

    или

    bazel run //tensorflow/tools/docs:tf_doctest -- --module=ops.array_ops

    --module относится к tensorflow.python .