Guía de Estilo General de MxOS¶
¡Tu manual para escribir documentación increíble!¶
- Authors:
Rénich Bon Ćirić <renich@mx-os.mx>
- Copyright:
CC-BY-SA 4.0 o >
- Organization:
Fundación MxOS, A.C.
Descripción¶
¡Bienvenid@ a la guía definitiva para crear documentación en ReStructured Text (RST)! Aquí te enseñaremos todos los trucos para que tus textos no solo sean claros, sino también ¡súper divertidos de leer!
Sphinx y Docutils: ¿Qué son y por qué importan?¶
Antes de sumergirnos en el fascinante mundo de reStructuredText, hablemos de dos herramientas clave: Docutils y Sphinx.
Piensa en Docutils como el motor que procesa tus archivos .rst. Es el conjunto de herramientas básicas que entiende la sintaxis y convierte tu texto en un formato estructurado.
Sphinx, por otro lado, es como un coche de carreras construido sobre ese motor 🏎️. Es un superset de Docutils, lo que significa que toma toda la potencia de Docutils y le añade un montón de funcionalidades increíbles, como la capacidad de generar sitios web de documentación completos, índices automáticos, resaltado de código avanzado y mucho más.
En resumen: todo lo que funciona en Docutils funciona en Sphinx, pero Sphinx te da superpoderes para crear documentación más rica y compleja.
Note
⚠️ ¡Ojo aquí! Como Sphinx y otras herramientas (como Forgejo) usan su propia “magia” para renderizar, el mismo archivo .rst puede verse un poco diferente dependiendo de dónde lo veas. Por eso, es una buena práctica renderizar tus documentos a HTML para ver cómo quedan y versionar ese HTML, o familiarizarte con las diferencias de renderizado entre plataformas como Sphinx y Forgejo. ¡Así te evitas sorpresas! 😉
Títulos: ¡El alma de tu documento!¶
Los títulos son como los letreros de tu documento, ¡ayudan a la gente a no perderse! Usamos el signo de igual (=) para los títulos principales. Se ven diferentes en HTML y PDF, pero la idea es la misma: ¡organizar tu contenido!
Para que veas cómo se renderiza, puedes usar pandoc:
# para HTML
pandoc -t html5 -o ejemplo.html ejemplo.rst
# para PDF
pandoc -t pdf -o ejemplo.pdf ejemplo.rst
Aquí vamos a usar muchos títulos para que veas todos los niveles.
Sub-títulos: ¡Para organizar tus ideas!¶
Cuando tu documento empieza a crecer, los subtítulos son tus mejores amigos para mantener todo en orden. Usamos signos de resta (-) para subrayarlos.
Si quieres añadir viñetas, ¡usa asteriscos (*)!
Asegúrate de que cada viñeta esté separada por una línea nueva de cualquier texto o título.
Si la información de una viñeta es muy larga, ¡no te preocupes! Puedes usar indentación (3 espacios, ¡recuerda!) para que se vea bonito y legible.
# ¡Incluso puedes meter código dentro de una viñeta! echo "Siempre y cuando esté bien indentado, claro."
Note
La indentación mágica es de 3 espacios. ¡Es la recomendación de Sphinx, nuestros gurús de la documentación!
Si quieres seguir con las viñetas después de un bloque de código o una nota, ¡deja un espacio en blanco entre ellos para que RST no se confunda!
Detalles: ¡A fondo con el formato!¶
Aquí nos metemos de lleno en los detalles más finos del formato. ¡Prepárate para el nivel pro!
Sub-sub-títulos con ^¶
Para esos temas que necesitan un nivel extra de organización, usamos el signo ^ para los sub-sub-títulos. ¡Así nadie se pierde!
¡Longitud de los subrayados!¶
¡Ojo aquí! Los subrayados (o “sobrerrayados”) deben ser exactamente igual de largos que el texto del título. Si son más largos, se ve un poco raro y rstcheck se enoja. ¡Así que a contar bien!
Tablas: ¡Organiza tus datos con estilo!¶
Las tablas son geniales para presentar información de forma ordenada. ¡Aquí te enseñamos cómo hacerlas sin sudar la gota gorda!
Tablas simples: ¡Fáciles y rápidas!¶
Son perfectas para datos sencillos. ¡Solo necesitas un poco de paciencia para alinear!
Ejemplo de tabla simple:¶
=============== ==================
Platillo Origen
=============== ==================
Tacos al pastor Ciudad de México
Cochinita pibil Yucatán
Mole poblano Puebla
=============== ==================
Tablas de cuadrícula: ¡Para los pros!¶
Si necesitas algo más complejo, con celdas que se expanden, las tablas de cuadrícula son tu mejor opción. ¡Un poco más de trabajo, pero el resultado vale la pena!
Ejemplo de tabla de cuadrícula:¶
+-----------------+----------------------+
| Ingrediente | Región de origen |
+=================+======================+
| Chile Habanero | Península de Yucatán |
+-----------------+----------------------+
| Nopal | Altiplano Central |
+-----------------+----------------------+
Enlaces: ¡Conecta tu contenido!¶
Los enlaces son la magia de la web, ¡y en RST también! Puedes conectar tu documento con sitios externos o con otras secciones dentro del mismo archivo.
Enlaces internos: ¡Salta entre secciones!¶
Para que tus lectores puedan ir de un lado a otro dentro de tu documento, crea “anclas” o puntos de referencia. Normalmente, los pones justo antes de un título, así:
.. _nombre-del-ancla:
Título de la Sección
====================
Luego, para enlazar a esa ancla con un texto personalizado, la sintaxis es:
`Texto que verá el lector <nombre-del-ancla_>`_
Imágenes: ¡Dale vida a tu texto!¶
Una imagen vale más que mil palabras, ¡y en tu documentación no es la excepción! Usa la directiva .. image:: seguida de la ruta al archivo.
Un ejemplo práctico y que siempre queda bien es alinear la imagen y añadirle un texto alternativo (¡súper importante para la accesibilidad!):
.. image:: /ruta/de/ejemplo/logo.png
:align: center
:alt: Logotipo de ejemplo
También es común que una imagen funcione como un enlace:
.. image:: /ruta/de/ejemplo/otro_logo.png
:target: https://mx-os.mx/
Listas de Definiciones: ¡Tu propio glosario!¶
¿Tienes términos técnicos o palabras clave que necesitan una explicación? ¡Las listas de definiciones son tu salvación! Son perfectas para crear glosarios o para aclarar conceptos.
La sintaxis es sencilla: el término, seguido de dos puntos (¡para que quede claro!), y luego su definición en una línea nueva con una sangría de 3 espacios.
- Taco al pastor:
Carne de cerdo marinada en adobo, cocinada en un asador vertical y servida en una tortilla de maíz. Generalmente se acompaña con piña, cebolla y cilantro. ¡Una delicia mexicana!
- Glosario:
Un término súper útil para referirse a una lista de definiciones. ¡Así de fácil!
Comentarios: ¡Notas secretas para ti!¶
¿Necesitas dejarte recordatorios o explicaciones en el código RST que no quieres que aparezcan en el documento final? ¡Usa los comentarios! Solo tienes que poner .. al inicio de una línea.
..
¡Hola! Esto es un comentario y nadie lo verá en el documento final.
Es como tu diario secreto de la documentación. 😉
.. Esto es un comentario de una sola línea. ¡Sencillo!
Otros trucos: ¡Magia en RST!¶
Aquí te compartimos algunos trucos extra para que tu documentación brille aún más.
- Espaciado de títulos:
Para que tus títulos principales respiren y se vean súper bien, ¡deja dos líneas en blanco antes de ellos! Así, tu documento será más legible y agradable a la vista.
- Bloques sin procesar (literal blocks):
¿Necesitas que un texto aparezca tal cual, sin que RST intente interpretarlo? ¡Usa los bloques sin procesar! Solo tienes que poner dos puntos dobles (::) al final de la línea anterior.
Aquí, el texto que ponga
no se va a procesar.
Y va a aparecer tal cual.
Admonitions: ¡Mensajes con estilo!¶
Los “Admonitions” son como cajas especiales para resaltar información importante. ¡Hay de muchos tipos y cada uno tiene su propio estilo!
Attention
¡Atención, atención! Para llamar la atención sobre algo importante.
Caution
¡Cuidado! Para indicar precaución.
Danger
¡Peligro! ¡Peligro! Para advertir sobre algo realmente serio.
Error
¡Ups! Para mostrar un error.
Hint
¡Un pequeño empujón! Para darte un tip o una pista.
Important
¡Esto es crucial! Para destacar algo muy importante.
Note
Hacer notas con un estilo predefinido.
Tip
Darte consejos o tips.
Warning
Hacer advertencias.
Por si no fuera poco, estos se pueden estilizar normalmente y podemos hasta crear los propios.
También puedes configurar el lenguaje a utilizar en Sphinx o pandoc para que los títulos de los “admonitions” se traduzcan a tu idioma.