Guía de estilo de documentación de TensorFlow

Mejores prácticas

  • Centrarse en la intención del usuario y la audiencia.
  • Use palabras cotidianas y mantenga oraciones cortas.
  • Use la construcción de oraciones, la redacción y el uso de mayúsculas consistentes.
  • Use encabezados y listas para que sus documentos sean más fáciles de escanear.
  • La Guía de estilo de Google Developer Docs es útil.

Reducción

Con algunas excepciones, TensorFlow usa una sintaxis Markdown similar a GitHub Flavored Markdown (GFM). Esta sección explica las diferencias entre la sintaxis de GFM Markdown y Markdown que se usa para la documentación de TensorFlow.

Escribir sobre código

Menciones de código en línea

Coloque `backticks` alrededor de los siguientes símbolos cuando se usen en el texto:

  • Nombres de argumentos: `input` , `x` , `tensor`
  • Nombres de tensores devueltos: `output` , `idx` , `out`
  • Tipos de datos: `int32` , `float` , `uint8`
  • Referencia de otros nombres de operaciones en el texto: `list_diff()` , `shuffle()`
  • Nombres de clases: `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 acento grave, por ejemplo:


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

Use enlaces relativos entre archivos en un solo repositorio de GitHub. Incluya la extensión del archivo.

Por ejemplo, este archivo que está leyendo es del repositorio https://github.com/tensorflow/docs . Por lo tanto, puede usar rutas relativas para vincular a otros archivos en el mismo repositorio como este:

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

Este es el enfoque preferido porque de esta manera funcionan todos los enlaces en tensorflow.org , GitHub y Colab . Además, el lector permanece en el mismo sitio cuando hace clic en un enlace.

Para enlaces a archivos que no están en el repositorio actual, use enlaces Markdown estándar con el URI completo. Prefiera vincular al URI de tensorflow.org si está disponible.

Para vincular al código fuente, use un vínculo 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 se enlace fuera de tensorflow.org , incluya un {:.external} en el enlace de Markdown para que se muestre el símbolo de "enlace externo".

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

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

  • Utilice: <a href="https://www.tensorflow.org/guide/data">https://www.tensorflow.org/guide/data</a>
  • No: <a href="https://www.tensorflow.org/guide/data?hl=en">https://www.tensorflow.org/guide/data?hl=en</a>

Imágenes

Los consejos del apartado anterior son para enlaces a páginas. Las imágenes se manejan de manera diferente.

Por lo general, no debe registrar imágenes y, en su lugar, agregar el equipo de TensorFlow-Docs a su RP y pedirles que alojen las imágenes en tensorflow.org . Esto ayuda a mantener bajo el tamaño de su repositorio.

Si envía imágenes a su repositorio, tenga en cuenta que algunos sistemas no manejan rutas relativas a las imágenes. Prefiere usar una URL completa que apunte a la ubicación final de la imagen en tensorflow.org .

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

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

  • Hay al menos uno . en el camino, y
  • La ruta parcial es única dentro del proyecto.

Las rutas de API están vinculadas para cada proyecto con una API de Python publicada en tensorflow.org . Puede vincular fácilmente varios subproyectos desde un solo archivo envolviendo los nombres de la API con acentos graves. Por ejemplo:

Para los símbolos con múltiples alias de ruta, hay una ligera preferencia por 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 usar MathJax dentro de TensorFlow al editar archivos Markdown, pero tenga en cuenta lo siguiente:

  • MathJax se representa correctamente en tensorflow.org .
  • MathJax no se representa correctamente en GitHub.
  • Esta notación puede resultar desagradable para los desarrolladores que no están familiarizados.
  • Para mantener la coherencia , tensorflow.org sigue las mismas reglas que Jupyter/Colab.

Use $$ 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 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 escribir o editar partes sustanciales de la documentación narrativa, lea la Guía de estilo de 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 tienen un complemento de revisión ortográfica disponible. También puede pegar su texto en un documento de Google u otro software de documentos para una revisión ortográfica y gramatical más sólida.
  • Usa una voz casual y amistosa. Escriba la documentación de TensorFlow como una conversación, como si estuviera hablando con otra persona uno a uno. Utilice un tono de apoyo en el artículo.
  • Evite los descargos de responsabilidad, las opiniones y los juicios de valor. Palabras como "fácilmente", "simplemente" y "simple" están cargadas de suposiciones. Algo puede parecerte fácil, pero ser difícil para otra persona. Trate de evitar estos siempre que sea posible.
  • Use oraciones simples y directas sin jerga complicada. Las oraciones compuestas, las cadenas de cláusulas y los modismos específicos de la ubicación pueden dificultar la comprensión y la traducción del texto. Si una oración se puede dividir en dos, probablemente debería hacerlo. Evite los puntos y comas. Use listas de viñetas cuando sea apropiado.
  • Proporcione contexto. No utilice abreviaturas sin explicarlas. No menciones proyectos que no sean de TensorFlow sin vincularlos. Explique por qué el código está escrito de esa manera.

Guía de uso

operaciones

En los archivos de rebajas, use # ⇒ en lugar de un solo signo 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, muestre el resultado en lugar de agregar un comentario (si la última expresión en una celda del cuaderno no está asignada a una variable, se muestra automáticamente).

En los documentos de referencia de la API, prefiera usar doctest para mostrar los resultados.

tensores

Cuando hables de un tensor en general, no escribas con mayúscula la palabra tensor . Cuando habla sobre el objeto específico que se proporciona o se devuelve de una operación, debe escribir en mayúscula la palabra Tensor y agregar acentos graves alrededor porque está hablando de un objeto Tensor .

No use la palabra Tensores (plural) para describir múltiples objetos Tensor a menos que realmente esté hablando de un objeto Tensors . En su lugar, diga "una lista (o colección) de objetos Tensor ".

Use 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 arriba, prefiera "eje" o "índice" sobre "dimensión" cuando se habla 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 solo eje con longitud 3.