Guía de estilo de documentación de TensorFlow

Mejores prácticas

  • Céntrese en la intención y la audiencia del usuario.
  • Utilice palabras cotidianas y mantenga oraciones cortas.
  • Utilice una construcción de oraciones, redacción y uso de mayúsculas coherentes.
  • Utilice títulos 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 utiliza una sintaxis de Markdown similar a GitHub Flavored Markdown (GFM). Esta sección explica las diferencias entre la sintaxis de GFM Markdown y el Markdown utilizado para la documentación de TensorFlow.

Escribir sobre código

Menciones en línea de código

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

  • Nombres de argumentos: `input` , `x` , `tensor`
  • Nombres de tensor devueltos: `output` , `idx` , `out`
  • Tipos de datos: `int32` , `float` , `uint8`
  • Referencia de otros nombres de operaciones en el texto: `list_diff()` , `shuffle()`
  • Nombres de clase: `tf.Tensor` , `Strategy`
  • Nombre de 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 comillas invertidas 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
```

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

Por ejemplo, este archivo que estás 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:

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, utilice enlaces estándar de Markdown con el URI completo. Prefiere 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.

Al vincular desde tensorflow.org , incluya un `` en el enlace de 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 de URI en el enlace:

  • Uso: <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

El consejo de la sección anterior es para enlaces a páginas. Las imágenes se manejan de manera diferente.

Por lo general, no debe registrar imágenes, sino agregar el equipo de TensorFlow-Docs a su PR 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 utilizar 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 API de un símbolo, incluya la ruta del símbolo entre comillas invertidas:

Se prefieren ligeramente los caminos completos, excepto los caminos largos. Las rutas se pueden abreviar eliminando los componentes de la ruta principal. 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 ajustando los nombres de las API con comillas invertidas. Por ejemplo:

Para símbolos con múltiples alias de ruta, existe una ligera preferencia por la ruta que coincida con la página API en tensorflow.org . Todos los alias redireccionarán a la página correcta.

Matemáticas en rebajas

Puedes usar MathJax dentro de TensorFlow al editar archivos Markdown, pero ten en cuenta lo siguiente:

  • MathJax se procesa correctamente en tensorflow.org .
  • MathJax no se procesa correctamente en GitHub.
  • Esta notación puede resultar desagradable para desarrolladores desconocidos.
  • Para mantener 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 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 la documentación para desarrolladores de Google .

Principios del buen estilo.

  • Revisa la ortografía y 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.
  • Utilice una voz informal y amigable. Escribe documentación de TensorFlow como si fuera una conversación, como si estuvieras hablando con otra persona uno a uno. Utilice un tono de apoyo en el artículo.
  • Evite descargos de responsabilidad, opiniones y juicios de valor. Palabras como "fácilmente", "sólo" y "simple" están cargadas de suposiciones. Algo puede parecerte fácil a ti, pero resultar difícil para otra persona. Trate de evitarlos siempre que sea posible.
  • Utilice oraciones simples y directas sin jerga complicada. Las oraciones compuestas, las cadenas de cláusulas y los modismos específicos de una ubicación pueden hacer que el texto sea difícil de entender y traducir. Si una oración se puede dividir en dos, probablemente debería hacerlo. Evite el punto y coma. Utilice listas de viñetas cuando sea apropiado.
  • Proporcionar contexto. No utilices abreviaturas sin explicarlas. No menciones proyectos que no sean de TensorFlow sin vincularlos. Explique por qué el código está escrito como está.

Guía de uso

operaciones

En archivos de rebajas, utilice # ⇒ en lugar de un único signo igual cuando desee 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 API prefieren usar doctest para mostrar los resultados.

Tensores

Cuando hables de un tensor en general, no escribas la palabra tensor con mayúscula. Cuando hablas del objeto específico que se proporciona o devuelve desde una operación, entonces debes escribir en mayúscula la palabra Tensor y agregar comillas invertidas alrededor porque estás hablando de un objeto Tensor .

No uses la palabra Tensores (plural) para describir múltiples objetos Tensor a menos que realmente estés hablando de un 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 comillas invertidas. 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 indicó anteriormente, prefiera "eje" o "índice" a "dimensión" cuando hable 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.