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 código Python ejecutable. Para habilitar la prueba, anteponga la línea con >>> (tres corchetes en á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 ejemplo de los consejos de TensorFlow 2 API Docs . (Tenga en cuenta que el rastreador de tareas de esta hoja ya no está en uso).

Haga que el código sea comprobable con DocTest

Actualmente, muchas cadenas de documentación utilizan comillas invertidas (```) para identificar el código. Para hacer que el código sea comprobable con DocTest:

Elimine las comillas invertidas (```) y use los corchetes izquierdos (>>>) delante de cada línea. Utilice (...) delante de líneas continuas.
Agregue una nueva línea para separar los fragmentos de DocTest del texto de Markdown para representarlos correctamente en tensorflow.org.

Personalizaciones

TensorFlow utiliza algunas personalizaciones en la lógica incorporada de doctest:

No compara valores flotantes como texto: los valores flotantes se extraen del texto y se comparan usando allclose con tolerancias liberales atol y rtol . Esto permite :
- Documentos más claros: los autores no necesitan incluir todos los decimales.
- Pruebas más sólidas: los cambios numéricos en la implementación subyacente nunca deberían provocar que falle una prueba documental.
Solo verifica el resultado si el autor incluye el resultado de 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 sobre la cadena de documentos

En general : el objetivo de doctest es proporcionar documentación y confirmar que funciona. Esto es diferente de las pruebas unitarias. Entonces:
- 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 que sería 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 excede el límite de 80 líneas, puede colocar la salida adicional en la nueva línea y DocTest la reconocerá. Por ejemplo, consulte los bloques de varias líneas a continuación.
Globales : los módulos `tf` , np y os siempre están disponibles en DocTest de TensorFlow.
Usar símbolos : En DocTest puedes 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 de `tf.random.normal` . Esto se debe a que `random.normal` no es 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 de que cadenas de documentos demasiado precisas provoquen 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'>`.

Utilice 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-preprocessing )

Si estás 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 uses esa copia en lugar de la de TensorFlow.

Por ejemplo: tf_estimator_doctest.py .

Pruebe en su 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:
- Utilice una instalación de 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, necesitará compilar TensorFlow desde el código fuente . Una vez que esté configurado para compilar desde el código 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 .