1. El lenguaje reStructuredText¶

El lenguaje reStructuredText (abreviado como reST) es un lenguaje de marcado ligero y fácil de leer, diseñado para escribir documentos técnicos, manuales y páginas web a partir de archivos de texto plano.

Esta es una página que sirve de ejemplo y resumen de la mayoría de las funciones útiles del lenguaje reStructuredText para Sphinx. Para ver el texto fuente de esta página debes clicar en el icono del ojo situado arriba a la derecha.

Con esta página se puede aprender a utilizar este lenguaje de marcado y se puede comprobar el funcionamiento de los estilos aplicados por el tema Furo de Sphinx.

Para saber más sobre reStructuredText:

Párrafos¶

Párrafo con texto resaltado.

Párrafo con texto resaltado fuerte.

Párrafo con texto en formato código.

Otro párrafo más: Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.

Listas¶

Lista numerada:

Primero
Segundo
Tercero

Lista no numerada:

Primero
- Sub primero primero
- Sub primero segundo
Segundo
Tercero

Término uno

Descripción del término uno.

Término dos

Descripción del término dos.

Que puede tener varios párrafos.

Tablas¶

Tabla en forma de cuadrícula:

Encabezado 1	Encabezado 2	Encabezado 3
Fila 1, col 1	Fila 1, col 2	Fila 1, col 3
Fila 2, col 1	Fila 2, col 2	Fila 2, col 3

Tabla en forma de lista:

Tabla 1.1tabla en forma de lista¶
Encabezado 1	Encabezado 2	Encabezado 3	Encabezado 4
Fila 1, col 1	Fila 1, col 2	Fila 1, col 3	Fila 1, col 4
Fila 2, col 1	Fila 2, col 2	Fila 2, col 3	Fila 2, col 4

Hipervínculos¶

Enlace a una página de Wikipedia sobre Python.

Enlace interno a la página principal de contenidos.

Descarga de una imagen.

Enlace a la Tabla 1.1.

Imágenes¶

Ejemplo de imagen centrada en el medio de la página con título. Al clicar sobre la imagen, se muestra en su tamaño real más grande:

../_images/flower.jpg — Figura 1.1Flor blanca.¶

Imagen de Siritas Keawnet en Pexels

Ejemplo de imagen a la derecha con texto alrededor. Al clicar sobre la imagen se abre un enlace a Wikipedia:

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum. Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

Advertencias¶

Nota

Esto es una aclaración, dato curioso o recordatorio importante. También se puede utilizar para conectar un tema con otro.

Título de la caja personalizado

Esta advertencia genérica tiene un título que se puede modificar a voluntad, de forma personalizada.

Advertencia

Esta advertencia se usa para alertar sobre fallos típicos, malentendidos o acciones que pueden estropear algo.

Consejo

Esta sugerencia o pista sirve para guiar al estudiante hacia la solución. Estimula el pensamiento crítico sin dar la respuesta directamente.

Puede mostrarse inicialmente cerrada para no dar pistas antes de que el estudiante lo pida expresamente, con la opción :collapsible: closed.

Consistencia: Asigna siempre el mismo tipo de contenido al mismo bloque para que el estudiante asocie el color con el tipo de mensaje de forma automática.

Notas a pie de página¶

Este texto necesita una aclaración mediante una nota al pie de página con numeración automática [1].

También puedes enlazar a otra nota a pie de página usando un nombre identificativo o etiqueta [2].

Por otro lado, Sphinx es la herramienta estándar para generar documentación de proyectos asociados a Python [3].

Fórmulas¶

El generador de páginas estáticas Sphinx permite añadir fórmulas a la documentación gracias al lenguaje LaTeX:

$ax^2 + bx + c = 0$

$x = \frac{-b \pm \sqrt{b^2 - 4ac}}{2a}$

Aplicaciones embebidas¶

En reStructuredText se puede añadir contenido html que sirva para incluir aplicaciones JavaScript embebidas, como simuladores.

Simulador de circuitos:

Simulador neumático:

Glosario de términos¶

Sphinx¶: Generador de documentación de código abierto escrito en Python. Convierte archivos de texto plano (usualmente en formato reStructuredText o Markdown) en sitios web HTML estáticos, manuales en PDF, ePub y otros formatos. Es la herramienta estándar de la industria para documentar proyectos en el ecosistema Python.
Furo¶: Tema que define el aspecto visual y la estructura estética de la documentación generada por Sphinx. Es limpio, minimalista y adaptable (responsive) diseñado específicamente para proyectos de documentación de Sphinx. Destaca por ofrecer navegación fluida tanto en pantallas móviles como de escritorio y soporte nativo para modos claro/oscuro.
Python¶: Lenguaje de programación de alto nivel, interpretado y multiparadigma. Es ampliamente conocido por su sintaxis limpia y legible, y funciona como la base tecnológica sobre la cual está construido y se ejecuta todo el sistema de Sphinx.

El lenguaje reStructuredText¶

Es un lenguaje de marcado ligero diseñado específicamente para la comunidad de Python. Su objetivo principal es facilitar la creación de documentos técnicos legibles tanto en su formato de texto plano de origen como una vez procesados y compilados por herramientas como Sphinx.

Notas: