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 liberalatol
yrtol
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
yos
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 dexxx
. 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 enNewLayer
.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 .
- Use una instalación pip tf-nightly actualizada
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 atensorflow.python
.