Guía de estilo para la documentación¶

Esta guía incluye información sobre el estilo esperado, la sintaxis específica de MkDocs, las distintas herramientas necesarias y la traducción de documentación, en lo que respecta a la redacción de nuevos contenidos y la traducción de contenidos existentes.

Estilo general¶

Los encabezamientos y títulos solo tendrían la primera palabra capitalizada.
Preferimos la ortografía estadounidense, con algunas libertades para el coloquialismo específico de la programación (p.e., "apps") y la verborrea de los sustantivos (p.e., "scrollable").
El deletreo de "artefact" y "artefacts" es la siguiente.
Usamos espacios simples tras un punto.
Utilizamos un solo guión rodeado de espacios como un guión largo (o un literal HTML —).
Cualquier referencia a un nombre de producto utilizaría la capitalina preferida del producto. (p.e., "macOS", "GTK", "pytest", "Pygame", "PyScript").
Si un término se utiliza "como código", entonces estaría entrecomillado como código en línea, encerrándolo entre comillas simples, en lugar de añadirlo al diccionario.
Evitamos utilizar términos como «simplemente», «solo» o «fácilmente» cunado se describen acciones que realizaría un usuario. Estos términos pueden leerse como peyorativos, especialmente cuando un usuario está experimentando dificultades.

Información referencial cruzada¶

Siempre que sea posible, debe hacer referencias cruzadas en la documentación. En esta sección se cubren distintas maneras de poder hacerse, cada cual está basada sobre el tipo de información que está siendo referenciada.

MkDocs muestra enlaces con formato Markdown estándar. Los hipervínculos web con formato Markdown estándar son los siguientes:

[Texto del enlace](https://ejemplo.com/)

También puede utilizar este formato para enlazar a un archivo local:

[Texto del enlace](ruta/al/archivo.md)

Para hacer referencia a secciones concretas de archivos, o a la documentación del API es necesario utilizar el formato de enlace de referencia de MkDocs.

Anclajes Markdown personalizados y referencias cruzadas de contenido¶

Markdown genera anclas para todos los encabezados (cualquier cosa en una sola línea que empiece con entre uno y seis símbolos #), basándose en el contenido del encabezado. Por ejemplo, el ancla generado para esta sección es custom-markdown-anchors-and-content-cross---referencing. Sin embargo, debido a la forma en que funcionan nuestras traducciones, cada vez que se hace referencia a un encabezado de sección, debe tener un ancla personalizada.

MkDocs admite la representación de una sintaxis de enlace de referencia que permite enlazar con varios otros elementos de la documentación mediante un enlace Markdown modificado. Esto incluye enlazar a, entre otras cosas, encabezados Markdown personalizados y anclajes de texto.

Los enlaces de referencia de MkDocs son cualquiera de los enlaces con el siguiente formato:

[Link text][link-target]

Se requieren anclajes de cabecera y contenido personalizados

Cualquier encabezado o sección de contenido al que se haga referencia en el contenido de texto a través de un enlace de referencia MkDocs en la documentación de BeeWare debe tener un ancla personalizada adjunta. De lo contrario, existe la posibilidad de romper los enlaces cuando se traduce el contenido del encabezado.

Si necesita enlazar a un ancla de cabecera, necesitará generar un ancla personalizada para el contenido previsto. La sintaxis general para establecer un ancla personalizada es la siguiente:

# Texto del encabezado { #anchor-name }

Por ejemplo, adaptar el ancla de esta sección a anclas-personalizadas se haría con el siguiente formato:

## Anclajes personalizados de Markdown { #custom-anchors }

También puede crear un ancla sobre contenido general, incluidos texto y bloques de código. El siguiente formato, con líneas nuevas de arriba y abajo, seŕian incluidas encima del contenido al cual desea enlazar:

Contenido superior.

[](){ #nombre-del-ancla }

Contenido inferior, que ahora está vinculado al ancla superior.

Una vez creados los anclajes usuales, puede enlazar con ellos desde el mismo documento, o en otras partes de la documentación.

Markdown estándar se utiliza para enlazar a un ancla en el mismo archivo, el cual está formateado como el siguiente:

[Texto del enlace](#anchor-name)

Para enlazar con un ancla de un documento independiente se utiliza el estilo de enlace de referencia de MkDocs, el cual está formateado como el siguiente:

[Link text][anchor-name]

Enlaces de referencia del API¶

El enlace de referencia de MkDocs también admite referencias cruzadas a la documentación del API, incluidas las clases documentadas, los métodos o atributos de las clases y las referencias a documentación externa específica.

Existen múltiples opciones para enlazar a una clase documentada, o a un método o atributo de una clase, independientemente de si se enlaza desde el mismo archivo o desde un archivo independiente. Al enlazar con clases, etc., debe incluir puntos suspensivos en el primer conjunto de corchetes para que el nombre aparezca como código en línea. Los corchetes no son necesarios solo si está utilizando texto personalizado que no debe ser representado como código en línea. Los puntos nunca deben incluirse en el segundo conjunto de corchetes.

El enlace a una clase mientras exhibe el espacio de nombres tiene el formato siguiente:

[`module.ClassName`][]

El enlace a una clase mientras se exhibe sólo el nombre de la clase tiene el formato siguiente:

[`ClassName`][module.ClassName]

Los atributos son los mismos que los anteriores, con el nombre del atributo incluido. A continuación se exhibe el espacio de nombres:

[`module.ClassName.attributename`][]

Como con las clases, solo exhibiendo el nombre del atributo está formateado como sigue:

[`attributename`][module.ClassName.attributename]

Los métodos deben exhibirse con () después del espacio de nombres y, por lo tanto, deben tratarse de forma diferente a los atributos. La siguiente es la manera adecuada de enlazar a un método:

[`module.ClassName.methodname()`][module.ClassName.methodname]

Lo siguiente solo exhibe la clase y el nombre del método. Esto también requiere incluir los paréntesis tras el nombre:

[`Classname.methodname()`][module.Classname.methodname]

Puede enlazar a una clase, método, o atributo mientras exhiba un texto arbitrario, utilizando el mismo método con el espacio de nombres aplicable. Hacer esto con una clase tiene el siguiente formato:

[link text][module.ClassName]

También es posible enlazar directamente a la documentación importante de Python, así como a la documentación de Pillow. Por ejemplo, para enlazar con la documentación de int:

[`int`][]

Para enlazar con la documentación de Image de Pillow:

[`PIL.Image.Image`][]

Consejos para el bloque de código¶

Resaltado de lenguaje y código¶

Puede especificar el idioma del código contenido en el bloque de código incluyendo el nombre del idioma después de los tres primeros puntos, sin espacio entre ellos. Esto da como resultado un resaltado apropiado del código cuando se representar. Por ejemplo, para especificar Python, empezarías el bloque de código con ``python.

Comandos de consola y el botón de copia¶

Si estás incluyendo comandos de consola, o comandos con salida, si lo etiquetas como console o doscon, dependiendo de si estás describiendo un sistema operativo tipo Unix (incluyendo macOS), o Windows. Puedes incluir el prompt proporcionado por el sistema operativo; sólo se copiará el comando al pulsar el botón copiar. Por ejemplo, si comienzas un bloque de código con ```console, e incluyes el siguiente contenido:

$ mkdir test
$ ls
test

A continuación, al pulsar en el botón de copia del bloque de código, sólo se copiarán los comandos y se ignorarán los avisos y la salida. Esto le permite indicar que son comandos de consola, al tiempo que permite a los usuarios utilizar el botón de copia de manera efectiva.

Resaltar líneas específicas de código¶

Puede resaltar líneas específicas de código. Por ejemplo, para resaltar la línea 2, añadiría un espacio después del lenguaje, seguido de {hl_lines="2"}. Así, su bloque de código comenzaría con ``python {hl_lines="2"}. El resultado es:

import toga
from toga.style.pack import COLUMNA, FILA

Puede resaltar varias líneas diferentes. Por ejemplo, python {hl_lines="3 5 9"} resaltaría las líneas 3, 5 y 9. También puedes resaltar un rango de líneas. Por ejemplo, python {hl_lines="3-8"} resalta las líneas 3 a 8. Puedes destacar múltiples intervalos con, p.ej., python {hl_lines="9-18 23-44"}.

Elementos de Markdown que requieren formato específico¶

Debido a la forma en que se generan los archivos de traducción, es importante incluir las líneas nuevas necesarias en la sintaxis Markdown para advertencias, notas, etiquetas, directivas Jinja, pie de imagen y alineación, etc.

Advertencias y notas¶

Las amonestación deben tener el siguiente formato, incluyendo una línea nueva antes y después del inicio y final de la amonestación:

Contenido superior.

/// advertencia | Título

Texto de la advertencia.

Segundo párrafo.

///

Contenido inferior.

Esto funciona de la misma manera con cualquier tipo de amonestación compatible. Por ejemplo, las amonestación de nota requieren el mismo formato y saltos de línea:

Contenido superior.

/// nota | Título de la nota

Texto de la nota aquí.

///

Contenido inferior.

Todos los tipos de amonestación admitidos están disponibles para su uso como amonestación.

Contenido por pestañas¶

El contenido en pestañas se formatea de la siguiente manera, incluyendo una línea nueva antes del inicio y después del final del bloque de contenido:

Contenido superior.

/// pestaña | Título de la pestaña uno

Texto de la pestaña uno

///

/// pestaña | Título de la pestaña dos

Texto de la pestaña dos.

///

/// pestaña | Título de la pestaña tres

Texto de la pestaña tres.

///

Contenido inferior.

Un tabulador con una amonestación anidada tendría el siguiente formato, incluyendo una línea nueva antes y después del bloque de contenido:

Contenido superior.

/// pestaña | Windows

Texto de la pestaña.

/// advertencia | Advertencia

Texto de la advertencia.

///

///

Contenido inferior.

Contenido colapsado¶

El contenido colapsado se formatea de la siguiente manera, incluyendo líneas nuevas:

Contenido superior.

/// details-note | Título del contenido oculto

Contenido colapsado.

///

Contenido inferior.

Todos los tipos de advertencia compatibles están disponibles para su uso con contenido contraído, sin embargo, debes declararlos como details-admonitiontype. Por lo tanto, un bloque contraído de tipo «nota» sería details-note (como se muestra arriba), un bloque contraído de tipo «advertencia» sería details-warning y así sucesivamente.

Directivas Jinja¶

Hay algunas pocas prestaciones de la documentación que utilizan directivas Jinja en el texto. Cualquier cosa que utilice las prestaciones de las directivas Jinja necesitan estar envuelta en líneas nuevas. Por ejemplo, el tutorial de BeeWare contiene condicionales Jinja basadas en variables para determinar qué amonestación mostrar encima de la página principal. Aquellas están formateadas como lo siguiente:

Contenido superior.



Contenido inferior.

También existe una sintaxis para sustituir símbolos o texto. Esta sintaxis es una variable envuelta en una pareja de llaves dobles coincidentes y, si está en su propia línea, debe incluir una nueva línea antes y después.

Contenido superior.

{{ variable }}

Contenido inferior.

Formato de imagen¶

Las imágenes pueden tener la anchura definida y pueden alinearse a la izquierda, a la derecha y al centro (con una advertencia sobre "al centro"). Las imágenes deben incluir siempre un texto alternativo significativo a efectos de accesibilidad.

Establecer la anchura de 300px en una imagen tendría el siguiente formato:

![Image alt text](../path/to/image.png){ width="300px" }

Alinear una imagen a la izquierda (o a la derecha) tendría el siguiente formato:

![Image alt text](../path/to/image.png){ align=left }

Para añadir un pie de foto a una imagen es necesario poner una línea nueva antes y después, y el formato es el siguiente:

Contenido superior.

![Texto alternativo de la imagen](/ruta/a/imagen.png)

/// pie de foto

Contenido del pie de foto.

///

Contenido inferior.

Alinear una imagen al centro no es posible con el atributo align. La solución alternativa consiste en colocar la imagen con un subtítulo vacío, y ésta se quedará centrada. Debe incluir líneas nuevas entre cada sección, y antes y después. El formato es el siguiente:

Contenido superior.

![Image alt text](../path/to/image.png)

/// pie de foto

///

Contenido inferior.

Complementos con formato Markdown específico¶

En las secciones siguientes se cubre cómo utilizar los complementos que requieren un formato Markdown específico.

Utilizar fragmentos para incluir contenido externo¶

Para más detalles sobre cómo incluir contenido externo desde un archivo local o una URL, consulte la documentación de la extensión de fragmentos. Los fragmentos deben utilizarse siempre que el documento no contenga directivas Jinja que deban ejecutarse (la ejecución de Jinja se produce junto con el procesamiento de fragmentos Snippet, por lo que no se procesará ningún Jinja del archivo). Los Snippet son necesarios si desea poder utilizar delimitadores que le permitan incluir partes específicas de un archivo por separado, p.e., el documento fuente se divide en secciones que se inyectarán por separado unas de otras.

Notas importantes:

Utilizamos -8<- como identificador de Snippets. La documentación muestra varias opciones; por favor, siga nuestro estilo.
Los archivos que se encuentran en el contenido compartido de BeeWare Docs Tools se tratan como contenido “local”. Por lo tanto, sólo se utilizará el nombre del archivo, como en -8<- "docs-style-guide.md", o si el contenido está en un subdirectorio, sólo el directorio y el nombre del archivo, como en -8<- "style/docs-style-guide.md".
Si incluyes contenido externo de un archivo de GitHub a través de una URL, debes utilizar la URL del contenido sin procesar, o se mostrará la página web completa integrada dondequiera que la incluyas.

El uso de macros para incluir contenido compartido de BeeWare Docs Tools¶

También puedes incluir contenido del directorio de contenido compartido de las herramientas BeeWare Docs utilizando el complemento de Macros MkDocs. Este método es necesario si el documento contiene directivas Jinja que deban ejecutarse, y sólo se utilizaría en esta situación. No funcionará con contenido externo a través de una URL. El Mecanismo de reemplazo de variables macros funciona con este método.

Existen opciones para incluir contenidos mediante macros:

Utilice la sintaxis Jinja include si desea incluir el documento sin ningún otro cambio manual en él.
Utilice la sintaxis Jinja extends si ha incluido la sintaxis block de Jinja en el documento, lo cual permite anular o añadir a secciones específicas.

`pyspelling`¶

Utilizamos el corrector ortográfico pyspelling. Se ejecuta durante las comprobaciones de hilado.

Cuando pyspelling identifica una palabra mal escrita, en la mayoría de los casos, debe corregirse en el contenido de la documentación.

En el caso raro que identifiques una palabra válida que no esté en el diccionario pyspelling, tienes dos opciones:

Si se trata de una palabra que es probable que se reutilice varias veces, deberías añadirla al documento spelling_wordlist del directorio docs, por orden alfabético.
Si se trata de una palabra que es poco probable que se vuelva a utilizar, puede envolverla en una etiqueta <nospell> / </nospell>, y pyspelling lo ignorará en línea.