Contribuer à la documentation de l'API TensorFlow

Docstrings testables

TensorFlow utilise DocTest pour tester des extraits de code dans les docstrings Python. L'extrait doit être du code Python exécutable. Pour activer les tests, ajoutez >>> (trois crochets à gauche) à la ligne. Par exemple, voici un extrait de la fonction tf.concat dans le fichier source 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>

Pour évaluer la qualité de la documentation de référence, consultez la section exemple des conseils TensorFlow 2 API Docs . (Sachez que le Task Tracker sur cette feuille n’est plus utilisé.)

Rendre le code testable avec DocTest

Actuellement, de nombreuses docstrings utilisent des backticks (```) pour identifier le code. Pour rendre le code testable avec DocTest :

• Supprimez les guillemets (```) et utilisez les crochets gauches (>>>) devant chaque ligne. Utilisez (...) devant les lignes continues.
• Ajoutez une nouvelle ligne pour séparer les extraits DocTest du texte Markdown afin d'obtenir un rendu correct sur tensorflow.org.

Personnalisations

TensorFlow utilise quelques personnalisations de la logique doctest intégrée :

• Il ne compare pas les valeurs flottantes sous forme de texte : les valeurs flottantes sont extraites du texte et comparées à l'aide allclose avec les tolérances libérales atol et rtol . Ceci permet :
  • Documents plus clairs : les auteurs n'ont pas besoin d'inclure toutes les décimales.
  • Tests plus robustes - Les modifications numériques dans l'implémentation sous-jacente ne devraient jamais provoquer l'échec d'un doctest.
• Il vérifie uniquement la sortie si l'auteur inclut la sortie pour une ligne. Cela permet d'obtenir des documents plus clairs car les auteurs n'ont généralement pas besoin de capturer des valeurs intermédiaires non pertinentes pour empêcher leur impression.

Considérations sur les chaînes de documentation

• Globalement : Le but de doctest est de fournir de la documentation, et de confirmer que la documentation fonctionne. Ceci est différent des tests unitaires. Donc:
  • Gardez les exemples simples.
  • Évitez les sorties longues ou compliquées.
  • Utilisez des nombres ronds si possible.
• Format de sortie : la sortie de l'extrait doit être directement sous le code qui génère la sortie. De plus, la sortie dans la docstring doit être exactement égale à ce que serait la sortie après l'exécution du code. Voir l'exemple ci-dessus. Consultez également cette partie dans la documentation DocTest. Si la sortie dépasse la limite de 80 lignes, vous pouvez placer la sortie supplémentaire sur la nouvelle ligne et DocTest la reconnaîtra. Par exemple, voir les blocs multilignes ci-dessous.
• Globals : Les modules `tf` , np et os sont toujours disponibles dans le DocTest de TensorFlow.

• Utiliser des symboles : Dans DocTest vous pouvez accéder directement aux symboles définis dans le même fichier. Pour utiliser un symbole qui n'est pas défini dans le fichier actuel, veuillez utiliser l'API publique de TensorFlow tf.xxx au lieu de xxx . Comme vous pouvez le voir dans l'exemple ci-dessous, `random.normal` est accessible via `tf.random.normal` . C'est parce que `random.normal` n'est pas visible dans 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=...>
    """
  

• Valeurs à virgule flottante : le doctest TensorFlow extrait les valeurs flottantes des chaînes de résultats et les compare à l'aide de np.allclose avec des tolérances raisonnables ( atol=1e-6 , rtol=1e-6 ). De cette façon, les auteurs n'ont pas à s'inquiéter des docstrings trop précis provoquant des échecs dus à des problèmes numériques. Collez simplement la valeur attendue.

• Sortie non déterministe : utilisez les points de suspension( ... ) pour les parties incertaines et DocTest ignorera cette sous-chaîne.

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

• Blocs multilignes : DocTest est strict sur la différence entre une instruction simple et une instruction multiligne. Notez l'utilisation de (...) ci-dessous :

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

• Exceptions : les détails de l'exception sont ignorés, à l'exception de l'exception déclenchée. Voir ceci pour plus de détails.

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

Utilisez une copie locale du projet de tf-doctest.

Certaines API de TensorFlow proviennent d'un projet externe :

• tf.estimator (de tensorflow_estimator )
• tf.summary tensorboard )
• tf.keras.preprocessing (de keras-preprocessing )

Si vous travaillez sur un projet externe ou sur des API TensorFlow hébergées dans un projet externe, ces instructions ne fonctionneront que si ce projet dispose de sa propre copie locale de tf_doctest et que vous utilisez cette copie à la place de celle de TensorFlow.

Par exemple : tf_estimator_doctest.py .

Testez sur votre machine locale

Il existe deux manières de tester localement le code de la docstring :

• Si vous modifiez uniquement la docstring d'une classe/fonction/méthode, vous pouvez la tester en transmettant le chemin de ce fichier à tf_doctest.py . Par exemple:

  python tf_doctest.py --file=<file_path>
  

  Cela l'exécutera en utilisant votre version installée de TensorFlow. Pour être sûr que vous exécutez le même code que celui que vous testez :

  • Utilisez une installation pip tf-nightly à jour pip install -U tf-nightly
  • Rebasez votre demande d'extraction sur une extraction récente de la branche principale de TensorFlow .

• Si vous modifiez le code et la docstring d'une classe/fonction/méthode, vous devrez alors créer TensorFlow à partir de source . Une fois que vous êtes configuré pour construire à partir des sources, vous pouvez exécuter les tests :

  bazel run //tensorflow/tools/docs:tf_doctest
  

  ou

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

  Le --module est relatif à tensorflow.python .