Convertidor de reStructuredText a HTML

Cómo funciona

reStructuredText es el lenguaje de documentación del mundo Python: el README.rst de un paquete de PyPI, la documentación escrita con Sphinx y el CHANGELOG de muchos proyectos de código abierto lo usan. Cuando quiera ver uno de esos archivos fuera de GitHub, o llevar su contenido a una página web, pegue el texto aquí. Por ejemplo, el título "Instalación" del README.rst de su paquete, sus pasos numerados, el comando pip introducido con :: y la tabla de opciones salen a la derecha como h2, ol, pre y table; un bloque .. note:: se convierte en un div titulado "Nota". El nivel de los títulos sigue la regla de docutils: lo da el orden en que aparece por primera vez cada carácter de subrayado, así que si usó = antes que -, = es el nivel uno y - el nivel dos. Estructuras admitidas: títulos con subrayado o sobrerrayado, párrafos, listas con viñetas y numeradas (anidadas), listas de definiciones y de campos, bloques de líneas, citas, transiciones, bloques literales y doctest, tablas simples y de rejilla, las directivas image, figure, code-block y los recuadros, y enlaces resueltos con destinos .. _nombre:. Las directivas propias de Sphinx, como toctree, contents e include, se omiten y se cuentan en la línea de resultado; no se tragan en silencio. La salida es código HTML: elija "Fragmento" para incrustarlo en una página y "Página completa" para abrirlo como archivo.

Esta herramienta también se busca como convertir rst a html, rst a html, restructuredtext a html, abrir archivo rst, rst to html, vista previa readme.rst.

¿Qué es reStructuredText (RST)?

reStructuredText es el lenguaje de marcado en texto plano que la comunidad de Python usa desde 2002; su extensión de archivo es .rst. Un título se escribe con una línea de ===== o ----- debajo, el énfasis con *asteriscos*, el código con ``dobles acentos graves`` y un enlace con el patrón `texto <dirección>`_. Lo que lo distingue de Markdown son las directivas: bloques como .. note::, .. image:: y .. code-block:: dan al documento una estructura ampliable. Los archivos README.rst de los paquetes de PyPI, los sitios de documentación generados con Sphinx y la documentación del propio Python están escritos en él; el convertidor de referencia es docutils.

¿Qué es HTML?

HTML es el lenguaje de páginas que entiende un navegador: marca la estructura del contenido con etiquetas como <h1> para un título, <p> para un párrafo, <ul> para una lista y <table> para una tabla. Esta herramienta convierte cada estructura RST en la etiqueta HTML del mismo significado; los recuadros y los bloques de código reciben nombres de clase para que se les pueda conectar una hoja de estilos. La salida no tiene apariencia propia (CSS), solo estructura: pegada en una entrada de blog o en un gestor de contenidos, toma por sí sola el estilo de esa página. El HTML en bruto y las direcciones javascript: no se dejan pasar a propósito.

¿Cuál es la diferencia entre RST y Markdown?

Los dos dan formato a texto plano, pero pertenecen a mundos distintos. Markdown es corto y flexible: # título, **negrita**, [enlace](dirección); lo usan GitHub, los foros y las aplicaciones de notas, tiene muchos dialectos y las tablas o los recuadros no forman parte del estándar. reStructuredText es más estricto y más rico: los títulos se subrayan, las directivas (.. note::, .. code-block::) y los roles (:sup:, :ref:) hacen el documento ampliable, y las tablas y las notas al pie son parte del estándar; por eso lo prefieren la documentación de Python y Sphinx. Uno se puede convertir en el otro automáticamente, pero no uno a uno: la mayoría de las estructuras de Markdown tienen equivalente en RST, mientras que las directivas de RST no lo tienen en Markdown.

Qué directivas se convierten y cuáles se omiten

La fuerza de RST son sus directivas (bloques que empiezan por .. nombre::), y algunas solo tienen sentido dentro de Sphinx. Esta herramienta convierte las directivas que producen contenido: image y figure pasan a elementos de imagen, code-block / code / sourcecode a un bloque de código con clase de lenguaje, y note / warning / tip / important / caution / danger / hint / attention / error a un recuadro cuyo título está escrito en el idioma de la página.

Las directivas que pertenecen al proceso de construcción y no al documento — toctree, contents, include, math, csv-table, list-table — no producen HTML; su cuerpo no se filtra a la salida y la línea de resultado las cuenta como "N directivas no admitidas omitidas", de modo que sabe que falta una sección sin repasar la salida. .. raw:: html no se admite a propósito: no se puede inyectar HTML en bruto en una página a través de una entrada RST.

Por qué la salida no 'parece' una página

Lo que ve en el panel derecho es código HTML, no una página con formato: las etiquetas están escritas a la vista. Es intencionado: el trabajo de la herramienta es hacer el texto transportable. Para ver el resultado, elija "Página completa", descargue el archivo .html y ábralo con doble clic; el navegador lo muestra como cualquier página.

La salida no lleva estilos (CSS); los recuadros se marcan con la clase admonition y los bloques de código con clases como language-python, para que pueda conectar su propia hoja de estilos. En los enlaces solo se conservan las direcciones http(s), mailto, tel y relativas; las direcciones javascript: y data: se sustituyen por #.

• Fragmento HTML → pegar en una entrada de blog, en el editor de un CMS o en una página existente
• Página completa → guardar como archivo y abrirlo en el navegador, adjuntarlo a un correo
• Si su fuente está en Markdown → use la herramienta Markdown a HTML; las dos sintaxis no se mezclan

Preguntas frecuentes

¿Cómo convierto un archivo RST a HTML?

Abra el archivo .rst en un editor de texto, copie su contenido y péguelo en el panel izquierdo; el HTML se genera a la derecha de inmediato. Para guardarlo como archivo, elija "Página completa" y toque Descargar. El texto no sale de su dispositivo: la conversión se hace dentro del navegador.

¿Por qué faltan en la salida las directivas de Sphinx como toctree o autodoc?

No son contenido, sino marcadores que Sphinx rellena desde otros archivos al construir la documentación; no se pueden producir a partir de un solo texto. La herramienta las omite y la línea de resultado dice cuántas directivas se omitieron. Las directivas de contenido — títulos, listas, tablas, bloques de código y recuadros — se convierten por completo.

¿Por qué los niveles de título no son los que esperaba?

En RST ningún carácter está ligado a un nivel fijo; igual que docutils, esta herramienta asigna los niveles en el orden en que cada estilo de subrayado aparece por primera vez en el documento. Un título con sobrerrayado cuenta como un estilo distinto del mismo carácter usado solo como subrayado. Si el documento empieza con = y después usa -, obtiene h1 y h2 en ese orden.

¿Qué pasa si pego Markdown?

Los títulos con # y los enlaces [texto](dirección) de Markdown no son sintaxis RST; salen como párrafos simples y la línea de resultado avisa de que no se encontró estructura. Para Markdown use la herramienta Markdown a HTML. RST se reconoce fácil por las líneas ===== o ----- bajo los títulos y por las líneas de directiva que empiezan por ..