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 deben llevar sólo la primera palabra en mayúscula.
Preferimos la ortografía estadounidense, con algunas libertades para el coloquialismo específico de la programación (por ejemplo, "apps") y la verbosidad de los sustantivos (por ejemplo, "scrollable").
La ortografía de "artefacto" y "artefactos" es la siguiente.
Usamos espacios simples después de un punto.
Utilizamos un solo guión rodeado de espacios como guión largo (o un literal HTML —).
Cualquier referencia al nombre de un producto debe utilizar la mayúscula preferida del producto. (por ejemplo, "macOS", "GTK", "pytest", "Pygame", "PyScript").
Si un término se utiliza "como código", debe citarse 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» al describir las acciones que debe realizar un usuario. Estos términos pueden interpretarse como peyorativos, especialmente cuando un usuario está experimentando dificultades.

Información de referencia cruzada¶

Siempre que sea posible, debe hacer referencias cruzadas en la documentación. En esta sección se describen las distintas formas de hacerlo, en función del tipo de información a la que se haga referencia.

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

[Link text](https://example.com/)

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

[Link text](path/to/file.md)

Para hacer referencia a secciones concretas de archivos o a la documentación de la 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 generada 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 renderización de una sintaxis de enlace de referencia que permite enlazar con otros elementos de la documentación mediante un enlace Markdown modificado. Esto incluye, entre otras cosas, enlaces a encabezados Markdown personalizados y anclajes de texto.

Los enlaces de referencia de MkDocs son 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 con un ancla de cabecera, deberá generar un ancla personalizada para el contenido previsto. La sintaxis general para establecer un ancla personalizada es la siguiente:

# Header text { #anchor-name }

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

## Custom Markdown anchors { #custom-anchors }

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

Content above.

[](){ #anchor-name }

Content below, that is now attached to the anchor above.

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

Markdown estándar se utiliza para enlazar con un ancla en el mismo archivo, cuyo formato es el siguiente:

[Link text](#anchor-name)

Para enlazar con un ancla de un documento independiente se utiliza el estilo de enlace de referencia de MkDocs, cuyo formato es el siguiente:

[Link text][anchor-name]

Enlaces de referencia API¶

La vinculación de referencias de MkDocs también admite referencias cruzadas a la documentación de la 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 sólo si está utilizando texto personalizado que no debe ser renderizado como código en línea. Los puntos nunca deben incluirse en el segundo conjunto de corchetes.

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

[`module.ClassName`][]

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

[`ClassName`][module.ClassName]

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

[`module.ClassName.attributename`][]

Al igual que en el caso de las clases, si sólo se muestra el nombre del atributo, el formato es el siguiente:

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

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

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

A continuación se muestra sólo el nombre de la clase y del método. Esto también requiere incluir los paréntesis después del nombre:

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

Puede enlazar a una clase, método o atributo mientras muestra 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 del núcleo 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 renderiza. Por ejemplo, para especificar Python, empezarías el bloque de código con ``python.

Comandos de consola y 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 hacer clic 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 COLUMN, ROW

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 resaltar múltiples rangos con, por ejemplo, python {hl_lines="9-18 23-44"}.

Elementos de Markdown que requieren un formato específico¶

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

Admoniciones y notas¶

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

Content above.

/// admonition | Title

Admonition text.

A second paragraph.

///

Content below.

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

Content above.

/// note | Note title

Note text here.

///

Content below.

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

Contenido por pestañas¶

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

Content above.

/// tab | Tab one title

Tab one text

///

/// tab | Tab two title

Tab two text.

///

/// tab | Tab three title

Tab three text.

///

Content below.

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

Content above.

/// tab | Windows

Tab text.

/// admonition | Admonition

Admonition text.

///

///

Content below.

Contenido colapsado¶

El contenido colapsado se formatea de la siguiente manera, incluyendo saltos de línea:

Content above.

/// details-note | Collapsed content title

Collapsed content.

///

Content below.

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 características de la documentación que utilizan directivas Jinja en el texto. Cualquier cosa que utilice las características de las directivas Jinja debe ir envuelta en nuevas líneas. Por ejemplo, el tutorial de BeeWare contiene condicionales Jinja basadas en variables para determinar qué advertencia mostrar en la página principal. El formato es el siguiente:

Content above.



Content below.

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

Content above.

{{ variable }}

Content below.

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 nueva línea antes y después, y el formato es el siguiente:

Content above.

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

/// caption

Caption content.

///

Content below.

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

Content above.

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

/// caption

///

Content below.

Plugins con formato Markdown específico¶

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

Uso de 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 Snippets. Snippets debe utilizarse siempre que el documento no contenga directivas Jinja que deban ejecutarse (la ejecución de Jinja se produce junto con el procesamiento de Snippets, por lo que no se procesará ningún Jinja del archivo). Snippets es necesario si desea poder utilizar delimitadores que le permitan incluir partes específicas de un archivo por separado, por ejemplo, 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 incrustada dondequiera que la incluyas.

Uso de macros para incluir contenido compartido de BeeWare Docs Tools¶

También puede incluir contenido del directorio de contenido compartido de las herramientas BeeWare Docs utilizando el Macros MkDocs plugin. Este método es necesario si el documento contiene directivas Jinja que deban ejecutarse, y sólo debe utilizarse 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 Jinja block en el documento, que le permite anular o añadir a secciones específicas.

`pyspelling`¶

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

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 raro caso de que identifique 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, debe 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 la ignorará en línea.