Guía de Estilo Oficial de MxOS¶

Estándares y Convenciones de Redacción en reStructuredText (RST)¶

Autores:

Rénich Bon Ćirić <renich@mx-os.mx>

Organización:

Fundación MxOS, A.C.

Fecha:

Septiembre 2026

Estado:

Estándar Activo

Propósito y Alcance¶

Este documento establece las directrices oficiales de formato, marcado y redacción técnica en reStructuredText (RST) para todos los proyectos, repositorios y publicaciones de la Fundación MxOS.

El objetivo es garantizar la máxima legibilidad, consistencia estilística y compatibilidad multiplataforma entre motores de renderizado como Docutils, Sphinx y visores web de forjas Git (tales como Forgejo o GitLab).

Fundamentos: Docutils y Sphinx¶

La documentación técnica de MxOS se fundamenta en la arquitectura estándar del ecosistema Python y Linux:

Docutils: Es el motor y especificación base de procesamiento de archivos .rst. Interpreta la sintaxis fundamental, construye el árbol de sintaxis abstracta (AST) y convierte el texto plano a formatos estructurados (HTML, LaTeX, manpages).
Sphinx: Es el marco generador de documentación técnica construido sobre Docutils. Extiende la sintaxis base mediante directivas avanzadas, gestión de índices temáticos, referencias cruzadas tipadas (roles de dominio), resaltado sintáctico de código con Pygments e internacionalización (gettext).

Diferencias de Renderizado entre Plataformas¶

Aunque la sintaxis fundamental es común, plataformas como Forgejo o GitHub procesan archivos .rst utilizando analizadores nativos de Docutils o bibliotecas intermedias, mientras que el portal web oficial (docs.mx-os.mx) se compila mediante Sphinx.

Nota

Toda documentación debe ser válida tanto para el estándar básico de Docutils como para Sphinx. Se debe verificar la sintaxis localmente mediante la herramienta rstcheck antes de realizar commits.

Prudencia

Incompatibilidad de la Directiva contents con el Tema Furo: No se debe incluir la directiva .. contents:: en documentos destinados al portal Sphinx (docs.mx-os.mx). El tema Furo genera automáticamente la tabla de contenidos en la barra lateral derecha («On this page»); la presencia explícita de .. contents:: es capturada por Furo y renderizada como un bloque de error crítico visual.

Estructura y Jerarquía de Títulos¶

La jerarquía de encabezados debe seguir una secuencia estricta y predecible. Queda prohibido saltarse niveles en la jerarquía estructural.

Nivel	Adorno	Uso Estándar
Título Principal	Sobrerrayado y subrayado con `=`	Título único del documento o página.
Subtítulo	Sobrerrayado y subrayado con `-`	Subtítulo descriptivo inmediato al título.
Sección H1	Subrayado con `=`	Divisiones mayores del documento.
Sección H2	Subrayado con `-`	Subsecciones temáticas.
Sección H3	Subrayado con `^`	Desgloses específicos de una subsección.
Sección H4	Subrayado con `"`	Elementos analíticos o puntos menores.

Regla Estricta de Longitud de Subrayados¶

La longitud de las líneas de adorno (sobrerrayados y subrayados) debe coincidir exactamente con el número de caracteres del texto del título.

Si la línea de subrayado es más corta o más larga que el título, los analizadores estrictos de RST emitirán advertencias y herramientas de integración continua como rstcheck fallarán la validación:

===================
Título Correcto RST
===================

Sección de Primer Nivel
=======================

Subsección de Segundo Nivel
---------------------------

Reglas de Espaciado e Indentación¶

Indentación Institucional de 3 Espacios¶

En la Fundación MxOS, el contenido subordinado dentro de directivas RST (tales como bloques de advertencia, opciones de tablas o elementos de listas de definiciones) debe utilizar una sangría uniforme de 3 espacios:

.. note::

   Este bloque utiliza exactamente 3 espacios de indentación respecto
   al margen izquierdo de la directiva.

Líneas en Blanco Obligatorias¶

Para evitar que los analizadores de RST colapsen párrafos o interpreten directivas como texto plano literal, es obligatorio insertar una línea en blanco:

Antes y después de cualquier directiva (.. code-block::, .. note::, .. toctree::).
Antes de iniciar una lista con viñetas o numerada que siga a un párrafo.
Entre un elemento de lista padre y una sub-lista anidada. Sin una línea en blanco previa a la sub-lista, Sphinx colapsa los elementos anidados dentro del párrafo del elemento padre en el HTML renderizado.

* Elemento principal de lista

  * Elemento anidado (la línea en blanco previa es obligatoria)
  * Segundo elemento anidado

* Siguiente elemento principal

Regla de Cero Espacios Alrededor de Diagonales¶

En toda la documentación técnica de MxOS, nunca se deben usar espacios alrededor de barras diagonales. Se debe escribir siempre término/término, jamás término / término:

Correcto: offline/air-gapped, QEMU/KVM, ansible/koji, mkosi/kiwi, y/o.
Incorrecto: offline / air-gapped, QEMU / KVM, ansible / koji, mkosi / kiwi, y / o.

Bloques de Código y Resaltado Sintáctico¶

Para incorporar fragmentos de código, archivos de configuración o comandos de terminal, se utiliza la directiva .. code-block:: especificando obligatoriamente el lenguaje sintáctico:

.. code-block:: bash

   #!/usr/bin/bash
   set -euo pipefail
   echo "Despliegue automatizado de Koji Hub"

Directrices para Bloques de Código¶

Lenguajes Soportados: bash, spec, python, crystal, c, cpp, zig, yaml, json, ini, rst, text.
Prohibición de :caption:: No utilizar la opción :caption: dentro de los bloques de código, a fin de preservar la compatibilidad uniforme entre Docutils plano y temas personalizados de Sphinx.
Bloques Literales Genéricos: Para salidas de terminal no coloreadas o texto ASCII sin formato, puede utilizarse el marcador de dos puntos dobles (::) seguido de una línea en blanco y sangría de 3 espacios:

+---------------------------------------------+
| Topología de Red: Servidor Koji Hub         |
| IP: 192.168.122.10/24  -  VLAN: 100         |
+---------------------------------------------+

Tablas de Datos¶

La documentación técnica utiliza dos tipos principales de tablas según la complejidad estructural de los datos.

Tablas Simples¶

Recomendadas para comparaciones breves y listas de atributos de una sola línea:

=================  =================  ===================================
Componente         Paquete RPM        Función Principal
=================  =================  ===================================
Koji Hub           koji-hub           Servicio web XML-RPC central
Koji Builder       koji-builder       Daemon de compilación Mock
Sigul Client       sigul              Firma remota de paquetes RPM
=================  =================  ===================================

Tablas de Rejilla (Grid Tables)¶

Recomendadas para matrices complejas con celdas de múltiples líneas, bloques de código o estructuras jerárquicas:

+-------------------+--------------------+--------------------------------+
| Parámetro         | Tipo de Dato       | Descripción Técnica            |
+===================+====================+================================+
| ``--buildsrpm``   | Booleano           | Empaqueta fuentes y spec sin   |
|                   |                    | ejecutar compilación binaria.  |
+-------------------+--------------------+--------------------------------+
| ``--rebuild``     | Ruta (String)      | Ejecuta compilación binaria    |
|                   |                    | completa dentro del chroot.    |
+-------------------+--------------------+--------------------------------+

Hipervínculos y Referencias Cruzadas¶

Enlaces Externos¶

Para enlazar a recursos en la web, se utiliza la sintaxis de enlace con texto visible:

`Repositorio de CentOS Stream 10 <https://gitlab.com/redhat/centos-stream/rpms>`_

Para mantener el texto limpio en documentos extensos, se recomienda definir las referencias al final del documento:

Consulte la documentación oficial de `Koji Project`_ y de `Fedora Packaging`_.

..
   Referencias Externas

.. _Koji Project: https://koji.fedoraproject.org/koji/
.. _Fedora Packaging: https://docs.fedoraproject.org/en-US/packaging-guidelines/

Referencias Internas y Anclas¶

Para navegar entre secciones del mismo documento o entre páginas del portal Sphinx:

Definir un ancla antes del título:

.. _seccion-bootstrap:

Procedimiento de Bootstrap
==========================

Enlazar al ancla:

Consulte el :ref:`seccion-bootstrap` para inicializar el chroot.

Mensajes de Aviso (Admonitions)¶

Las directivas de aviso destacan información relevante para el operador según su nivel de criticidad técnica:

Directiva	Caso de Uso Operativo
`.. note::`	Información contextual, detalles de diseño o aclaraciones metodológicas.
`.. tip::`	Recomendaciones de rendimiento, atajos de teclado o mejores prácticas.
`.. important::`	Requisitos indispensables o pasos obligatorios para el éxito de una tarea.
`.. warning::`	Advertencias sobre posibles fallos de compilación, rotura de dependencias o incompatibilidades.
`.. caution::`	Riesgos graves de pérdida de datos, corrupción de repositorios o desconfiguración de producción.

Ejemplo de Uso:

.. caution::
   No ejecute ``git push --force`` sin especificar el commit base esperado;
   podría sobrescribir el trabajo concurrente de otros mantenedores.

Comentarios Internos¶

Los comentarios son notas técnicas destinadas a los editores del archivo que no se procesan en la salida HTML o PDF. Se definen anteponiendo dos puntos y un espacio:

..
   TODO: Actualizar esta sección cuando Koji 1.35 esté disponible en EPEL 10.

.. Comentario breve de una sola línea.

Validación y Calidad del Marcado¶

Todo colaborador debe auditar la sintaxis de sus archivos antes de someter un Pull Request mediante el analizador estricto:

rstcheck ruta/al/archivo.rst

Criterios de Aceptación: * Cero errores de sintaxis (Success! No issues detected). * Cero inconsistencias en la longitud de subrayados de títulos. * Cumplimiento total de la regla de CERO espacios alrededor de diagonales. * Ausencia de espacios en blanco al final de línea (trailing whitespace).