Contribuya a la documentación de la API de TensorFlow

Cadenas de documentación comprobables

TensorFlow usa DocTest para probar fragmentos de código en cadenas de documentación de Python. El fragmento debe ser un código Python ejecutable. Para habilitar la prueba, anteponga a la línea >>> (tres corchetes de ángulo izquierdo). Por ejemplo, aquí hay un extracto de la función tf.concat en el archivo fuente 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>

Para evaluar la calidad de la documentación de referencia, consulte la sección de ejemplos de los consejos de TensorFlow 2 API Docs . (Tenga en cuenta que el Rastreador de tareas en esta hoja ya no está en uso).

Hacer que el código sea comprobable con DocTest

Actualmente, muchas cadenas de documentos usan acentos graves (```) para identificar el código. Para hacer que el código sea comprobable con DocTest:

Elimina los acentos graves (```) y usa los corchetes izquierdos (>>>) delante de cada línea. Use (...) delante de líneas continuas.
Agregue una nueva línea para separar los fragmentos de DocTest del texto de Markdown para que se represente correctamente en tensorflow.org.

Personalizaciones

TensorFlow utiliza algunas personalizaciones en la lógica de prueba de documentos integrada:

No compara valores flotantes como texto: los valores flotantes se extraen del texto y se comparan usando allclose con liberal atol y rtol tolerences . Esto permite :
- Documentos más claros: los autores no necesitan incluir todos los lugares decimales.
- Pruebas más sólidas: los cambios numéricos en la implementación subyacente nunca deberían hacer que una prueba de documento falle.
Solo verifica la salida si el autor incluye salida para una línea. Esto permite documentos más claros porque los autores generalmente no necesitan capturar valores intermedios irrelevantes para evitar que se impriman.

Consideraciones de cadenas de documentación

En general : el objetivo de doctest es proporcionar documentación y confirmar que la documentación funciona. Esto es diferente de las pruebas unitarias. Asi que:
- Mantenga los ejemplos simples.
- Evite salidas largas o complicadas.
- Utilice números redondos si es posible.
Formato de salida : la salida del fragmento debe estar directamente debajo del código que genera la salida. Además, la salida en la cadena de documentación debe ser exactamente igual a la salida después de ejecutar el código. Vea el ejemplo anterior. Además, consulte esta parte en la documentación de DocTest. Si la salida supera el límite de 80 líneas, puede colocar la salida adicional en la nueva línea y DocTest la reconocerá. Por ejemplo, vea los bloques de varias líneas a continuación.
Globals : los `tf` , np y os siempre están disponibles en DocTest de TensorFlow.
Usar símbolos : En DocTest puede acceder directamente a los símbolos definidos en el mismo archivo. Para usar un símbolo que no está definido en el archivo actual, use la API pública de TensorFlow tf.xxx en lugar de xxx . Como puede ver en el siguiente ejemplo, se accede a ` `random.normal` a través `tf.random.normal` . Esto se debe a que `random.normal` no está visible en 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=...>
  """
```
Valores de punto flotante : el doctest de TensorFlow extrae valores flotantes de las cadenas de resultados y los compara usando np.allclose con tolerancias razonables ( atol=1e-6 , rtol=1e-6 ). De esta manera, los autores no necesitan preocuparse por cadenas de documentos demasiado precisas que causen fallas debido a problemas numéricos. Simplemente pegue el valor esperado.

Salida no determinista : use puntos suspensivos ( ... ) para las partes inciertas y DocTest ignorará esa subcadena.

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

Bloques de varias líneas : DocTest es estricto en cuanto a la diferencia entre una declaración de una sola línea y una de varias líneas. Tenga en cuenta el uso de (...) a continuación:
```
if x > 0:
  print("X is positive")
model.compile(
  loss="mse",
  optimizer="adam")
    
```

Excepciones : los detalles de la excepción se ignoran, excepto la excepción que se genera. Vea esto para más detalles.

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

Use una copia local del proyecto de tf-doctest.

Algunas API en TensorFlow provienen de un proyecto externo:

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

Si está trabajando en un proyecto externo o en las API de TensorFlow alojadas en un proyecto externo, estas instrucciones no funcionarán a menos que ese proyecto tenga su propia copia local de tf_doctest y use esa copia en lugar de la de TensorFlow.

Por ejemplo: tf_estimator_doctest.py .

Prueba en tu máquina local

Hay dos formas de probar el código en la cadena de documentación localmente:

Si solo está cambiando la cadena de documentación de una clase/función/método, puede probarlo pasando la ruta de ese archivo a tf_doctest.py . Por ejemplo:
```
python tf_doctest.py --file=<file_path>
```
Esto lo ejecutará usando su versión instalada de TensorFlow. Para asegurarse de que está ejecutando el mismo código que está probando:
- Use una instalación pip tf-nightly actualizada pip install -U tf-nightly
- Vuelva a basar su solicitud de extracción en una extracción reciente de la rama maestra de TensorFlow .
Si está cambiando el código y la cadena de documentación de una clase/función/método, deberá compilar TensorFlow desde la fuente . Una vez que esté configurado para compilar desde la fuente, puede ejecutar las pruebas:
```
bazel run //tensorflow/tools/docs:tf_doctest
```
o
```
bazel run //tensorflow/tools/docs:tf_doctest -- --module=ops.array_ops
```
El --module es relativo a tensorflow.python .