Guía de estilo de documentación de TensorFlow

Mejores prácticas

  • Céntrate en la intención del usuario y en la audiencia.
  • Utiliza palabras cotidianas y frases cortas.
  • Utilice una estructura de oraciones, una redacción y un uso de mayúsculas coherentes.
  • Utilice encabezados y listas para que sus documentos sean más fáciles de consultar.
  • La guía de estilo de Google Developer Docs resulta útil.

Reducción

Salvo algunas excepciones, TensorFlow utiliza una sintaxis Markdown similar a la de GitHub Flavored Markdown (GFM). Esta sección explica las diferencias entre la sintaxis Markdown de GFM y la utilizada en la documentación de TensorFlow.

Escribe sobre código

Menciones en línea de código

Cuando utilices los siguientes símbolos en un texto, `backticks` entre comillas invertidas:

  • Nombres de los argumentos: `input` , `x` , `tensor`
  • Nombres de tensores devueltos: `output` , `idx` , `out`
  • Tipos de datos: `int32` , `float` , `uint8`
  • Otros nombres de operaciones mencionados en el texto: `list_diff()` , `shuffle()`
  • Nombres de clase: `tf.Tensor` , `Strategy`
  • Nombre del archivo: `image_ops.py` , `/path_to_dir/file_name`
  • Expresiones o condiciones matemáticas: `-1-input.dims() <= dim <= input.dims()`

bloques de código

Utilice tres acentos graves para abrir y cerrar un bloque de código. Opcionalmente, especifique el lenguaje de programación después del primer grupo de acentos graves, por ejemplo:


```python
# some python code here
```

Utilice enlaces relativos entre archivos en un único repositorio de GitHub. Incluya la extensión del archivo.

Por ejemplo, este archivo que está leyendo proviene del repositorio https://github.com/tensorflow/docs . Por lo tanto, puede usar rutas relativas para enlazar con otros archivos del mismo repositorio de esta manera:

  • [Basics](../../guide/basics.ipynb) produce Basics .

Este es el método preferido porque así funcionan los enlaces en tensorflow.org , GitHub y Colab . Además, el lector permanece en el mismo sitio al hacer clic en un enlace.

Para enlazar a archivos que no se encuentran en el repositorio actual, utilice enlaces Markdown estándar con la URI completa. Si está disponible, es preferible enlazar a la URI de tensorflow.org .

Para enlazar al código fuente, utilice un enlace que comience con https://www.github.com/tensorflow/tensorflow/blob/master/ , seguido del nombre del archivo que comienza en la raíz de GitHub.

Cuando cree un enlace desde tensorflow.org , incluya una `` en el enlace Markdown para que se muestre el símbolo de "enlace externo".

  • [GitHub](https://github.com/tensorflow/docs) produce GitHub

No incluya parámetros de consulta URI en el enlace:

  • Uso: https://www.tensorflow.org/guide/data
  • Nota: https://www.tensorflow.org/guide/data?hl=en

Imágenes

Los consejos de la sección anterior se refieren a enlaces a páginas. Las imágenes se gestionan de forma diferente.

En general, no deberías incluir las imágenes en el repositorio; en su lugar, agrega al equipo de TensorFlow-Docs a tu solicitud de extracción y pídeles que alojen las imágenes en tensorflow.org . Esto ayuda a reducir el tamaño de tu repositorio.

Si envías imágenes a tu repositorio, ten en cuenta que algunos sistemas no admiten rutas relativas a las imágenes. Es preferible usar una URL completa que apunte a la ubicación final de la imagen en tensorflow.org .

Los enlaces de la API se convierten cuando se publica el sitio. Para enlazar a la página de referencia de la API de un símbolo, encierre la ruta del símbolo entre comillas invertidas:

Se prefieren ligeramente las rutas completas, excepto las rutas largas. Las rutas se pueden abreviar eliminando los componentes iniciales. Las rutas parciales se convertirán en enlaces si:

  • Hay al menos un . en la ruta, y
  • La ruta parcial es única dentro del proyecto.

Las rutas de la API están vinculadas para cada proyecto con una API de Python publicada en tensorflow.org . Puedes vincular fácilmente varios subproyectos desde un solo archivo encerrando los nombres de las API entre comillas invertidas. Por ejemplo:

Para los símbolos con múltiples alias de ruta, se prefiere ligeramente la ruta que coincide con la página de la API en tensorflow.org . Todos los alias redirigirán a la página correcta.

Matemáticas en Markdown

Puede utilizar MathJax dentro de TensorFlow al editar archivos Markdown, pero tenga en cuenta lo siguiente:

  • MathJax se visualiza correctamente en tensorflow.org .
  • MathJax no se visualiza correctamente en GitHub.
  • Esta notación puede resultar desconcertante para los desarrolladores que no estén familiarizados con ella.
  • Para garantizar la coherencia, tensorflow.org sigue las mismas reglas que Jupyter/Colab.

Utilice $$ alrededor de un bloque de MathJax:

$$
E=\frac{1}{2n}\sum_x\lVert (y(x)-y'(x)) \rVert^2
$$

\[ E=\frac{1}{2n}\sum_x\lVert (y(x)-y'(x)) \rVert^2 \]

Envuelva las expresiones MathJax en línea con $ ... $ :


This is an example of an inline MathJax expression: $ 2 \times 2 = 4 $

Este es un ejemplo de una expresión MathJax en línea: \( 2 \times 2 = 4 \)

Los delimitadores \\( ... \\) también funcionan para matemáticas en línea, pero la forma $ a veces es más legible.

Estilo de prosa

Si va a redactar o editar partes sustanciales de la documentación narrativa, lea la Guía de estilo de la documentación para desarrolladores de Google .

Principios del buen estilo

  • Revisa la ortografía y la gramática de tus contribuciones. La mayoría de los editores incluyen un corrector ortográfico o un complemento para ello. También puedes pegar el texto en un documento de Google Docs u otro programa de documentos para una revisión ortográfica y gramatical más exhaustiva.
  • Utiliza un tono informal y amigable. Redacta la documentación de TensorFlow como si fuera una conversación, como si estuvieras hablando con otra persona cara a cara. Mantén un tono comprensivo en el artículo.
  • Evita las aclaraciones, las opiniones y los juicios de valor. Palabras como «fácilmente», «simplemente» y «sencillo» conllevan muchas suposiciones. Algo puede parecerte fácil, pero ser difícil para otra persona. Intenta evitarlas siempre que sea posible.
  • Utilice oraciones sencillas y concisas, sin jerga complicada. Las oraciones compuestas, las cadenas de cláusulas y las expresiones idiomáticas específicas pueden dificultar la comprensión y la traducción del texto. Si una oración se puede dividir en dos, probablemente debería hacerse. Evite los puntos y comas. Utilice listas con viñetas cuando sea apropiado.
  • Proporciona contexto. No uses abreviaturas sin explicarlas. No menciones proyectos que no sean de TensorFlow sin enlazar a ellos. Explica por qué el código está escrito de esa manera.

Guía de uso

Operaciones

En los archivos Markdown, utilice # ⇒ en lugar de un solo signo de igual cuando quiera mostrar lo que devuelve una operación.

# 'input' is a tensor of shape [2, 3, 5]
tf.expand_dims(input, 0)  # ⇒ [1, 2, 3, 5]

En los cuadernos, se muestra el resultado en lugar de añadir un comentario (si la última expresión de una celda del cuaderno no está asignada a una variable, se muestra automáticamente).

En la documentación de referencia de la API, se prefiere usar doctest para mostrar los resultados.

tensores

Cuando te refieres a un tensor en general, no escribas la palabra "tensor" con mayúscula inicial. Cuando te refieres al objeto específico que se proporciona a una operación o que esta devuelve, entonces sí debes escribir la palabra "Tensor" con mayúscula inicial y añadir comillas invertidas a su alrededor, porque te refieres a un objeto Tensor .

No utilice la palabra «Tensores » (en plural) para describir varios objetos Tensor a menos que se refiera específicamente a un solo objeto Tensors . En su lugar, diga «una lista (o colección) de objetos Tensor ».

Utilice la palabra " forma" para detallar los ejes de un tensor y muestre la forma entre corchetes con acentos graves. Por ejemplo:


If `input` is a three-axis `Tensor` with shape `[3, 4, 3]`, this operation
returns a three-axis `Tensor` with shape `[6, 8, 6]`.

Como se mencionó anteriormente, es preferible usar "eje" o "índice" en lugar de "dimensión" al hablar de los elementos de la forma de un Tensor . De lo contrario, es fácil confundir "dimensión" con la dimensión de un espacio vectorial. Un "vector tridimensional" tiene un único eje de longitud 3.