reStructuredText ( RST , ReST o reST ) es un formato de archivo para datos textuales que se utiliza principalmente en la comunidad del lenguaje de programación Python para documentación técnica .
Extensión de nombre de archivo | .rst |
---|---|
Tipo de medio de Internet | texto / x-rst |
Desarrollado por | David Goodger |
Versión inicial | 2 de abril de 2002 |
Último lanzamiento | Revisión 8407 (29 de octubre de 2019 ) |
¿ Formato abierto ? | Dominio publico |
Sitio web | docutils |
Es parte del proyecto Docutils del Python Doc-SIG (Documentation Special Interest Group), cuyo objetivo es crear un conjunto de herramientas para Python similar a Javadoc para Java o Plain Old Documentation (POD) para Perl . Docutils puede extraer comentarios e información de programas Python y formatearlos en varias formas de documentación del programa. [1]
En este sentido, reStructuredText es un lenguaje de marcado ligero diseñado para ser (a) procesable por software de procesamiento de documentación como Docutils, y (b) fácilmente legible por programadores humanos que leen y escriben código fuente Python .
Historia
Hubo una serie de problemas con el lenguaje de marcado ligero anterior StructuredText (desarrollado por Zope ), y reST se desarrolló para solucionarlos. [2] El nombre reStructuredText fue elegido para indicar que reST es un "texto estructurado revisado, reelaborado y reinterpretado". [3]
reST comenzó a tener un uso significativo en la comunidad de Python en 2002. [ cita requerida ]
Implementación de referencia
La implementación de referencia del analizador reST es un componente del marco de procesamiento de texto Docutils en el lenguaje de programación Python , pero hay otros analizadores disponibles.
No hay un tipo de mimo oficial registrado para texto reestructurado, pero el no oficial sí lo es text/x-rst
. [4]
Aplicaciones
reStructuredText se usa comúnmente para documentación técnica, por ejemplo, en la documentación de bibliotecas de Python. [5] Sin embargo, es adecuado para una amplia variedad de textos.
Desde 2008, reST ha sido un componente central del sistema de generación de documentos Sphinx de Python .
Trac también admite reStructuredText, [6] al igual que GitHub y Bitbucket .
En 2011, Distributed Proofreaders , que preparó textos para el Proyecto Gutenberg , estaba considerando la adopción de reST como formato básico a partir del cual se podrían generar otros formatos de libros electrónicos. [7] [ necesita actualización ]
En julio de 2016, el proyecto del kernel de Linux decidió pasar de la documentación basada en DocBook a reStructuredText y la cadena de herramientas Sphinx . [8]
La herramienta de creación de software CMake cambió de un lenguaje de marcado personalizado a reStructuredText en la versión 3.0 para su documentación. [9]
Ejemplos de marcado reST
Encabezados
Encabezado de sección==============Encabezado de subsección-----------------
Liza
- Un elemento de lista de viñetas - Segundo elemento - Un elemento secundario- El espacio entre elementos separa los elementos de la lista* Diferentes símbolos de viñetas crean listas separadas- Tercer artículo1) Un elemento de lista enumerado2) Segundo artículo a) Subtema que se desarrolla extensamente y, por lo tanto, necesita para ser envuelto. Tenga en cuenta la sangría que debe coincidir con el comienzo del texto, no con el enumerador. i) Los elementos de la lista pueden incluso incluir saltos de párrafo.3) Tercer artículo#) Otro elemento de lista enumerado#) Segundo artículo
Imagenes
.. image :: /path/to/image.jpg
Enlaces con nombre
Una oración con enlaces a `Wikipedia`_ y al` archivo del kernel de Linux`_ ... _Wikipedia: https://www.wikipedia.org/ .. _Archivo del kernel de Linux: https://www.kernel.org/
Enlaces anónimos
Otra oración con un `enlace anónimo al sitio web de Python`__ .__ https://www.python.org/
NB: los enlaces con nombre y los enlaces anónimos se escriben con acentos graves (`) y no con apóstrofos (').
Bloques literales
:: algún texto literalEsto también se puede usar en línea al final de un párrafo, así : algo de texto más literal.. código :: python print ("Una directiva de bloque literal marcada explícitamente como código Python")
Ver también
Referencias
- ↑ Mertz, David (1 de febrero de 2003). "Asuntos XML: reStructuredText" . IBM developerWorks . Consultado el 5 de octubre de 2016 .
- ^ Goodger, David (24 de mayo de 2016). "reStructuredText: Componente analizador y sintaxis de marcado de Docutils" . Proyecto Docutils . Consultado el 5 de octubre de 2016 .
- ^ Goodger, David (26 de febrero de 2016). "Docutils FAQ (Preguntas más frecuentes)" . Proyecto Docutils . Consultado el 5 de octubre de 2016 .
- ^ "¿Cuál es el tipo MIME oficial para los datos reStructuredText? En las Preguntas frecuentes de Docutils" . Proyecto Docutils . Consultado el 20 de diciembre de 2017 .
- ^ Goodger, David (2 de abril de 2002). "PEP 287 - Formato de cadena de documentos de texto reestructurado" . Fundación de software Python . Consultado el 5 de octubre de 2016 .
- ^ "Soporte reStructuredText en Trac" . Trac . 2016-09-13 . Consultado el 5 de octubre de 2016 .
- ^ Newby, Greg (8 de enero de 2011). "Acta de la reunión del 11 de diciembre de 2010" . Correctores de pruebas distribuidos . Consultado el 8 de enero de 2011 .
- ^ "Documentación del núcleo con Sphinx, parte 1: cómo llegamos aquí" . LWN.net. 2016-07-06 . Consultado el 27 de octubre de 2016 .
- ^ "Notas de la versión de CMake 3.0.0" . Kitware, Inc. 2014-06-10 . Consultado el 5 de octubre de 2016 .
enlaces externos
- Sitio web oficial de reStructuredText con páginas de referencia