Introducción a RST y Sphinx para colaboradores de libros de texto
¿Qué es la RST?
RST significa ReStructured Text. Es el lenguaje de marcado estándar utilizado para documentar paquetes en python. Sphinx es el paquete de Python que genera un sitio web html a partir de archivos RST, y es el que estamos utilizando para generar este sitio. Para leer más sobre por qué elegimos RST en lugar de markdown o Latex, lee la siguiente sección, ¿Por qué RST?.
¿Por qué RST?
De serie, RST soporta estilos definidos globalmente, numeración y referencias de figuras, renderizado de funciones Latex, personalización de visualización de imágenes y más. Además, el texto reestructurado ya era el idioma preferido para la documentación del ecosistema AguaClara.
Configuración de RST para el desarrollo
Hay dos formas de visualizar rápidamente un archivo RST. La primera es usar un plugin Atom que renderiza la vista junto con el código fuente. Esta es una buena prueba inicial para asegurarse de que la RST es la RST correcta y se ve en su mayoría correcta. Sin embargo, algunas funcionalidades, como cualquier extensión proporcionada por Sphinx, no se ejecutarán en la vista previa. Para ver el HTML final que se mostrará en la web, tendrás que usar el segundo método, ejecutar Sphinx localmente para generar completamente el código html. Una vez que estés satisfecho con tu trabajo y quieras enviarlo al libro de texto, tendrás que incorporarlo a la rama maestra. Para ello, consulta Publishing online.
Instalación de los plugins de Atom
If you are using the Atom IDE to write RST, you can use the rst-preview-pandoc plugin to auto-generate a live RST preview within atom (much like the markdown-preview-plus preview page.) To get rst-preview working, you’ll need to install language-restructuredtext via atom and Pandoc via your command line ($pip install pandoc). If everything worked, you can use ctrl + shift + e to toggle a display window for the live-updated RST preview.
Construir RST localmente con Sphinx
Usamos Sphinx para construir RST local y remotamente. Sigue estos pasos para obtener Sphinx y ejecutarlo localmente:
Consigue Python 3.5+ y pipenv (
$pip install pipenv)Instala todas las dependencias y configura un entorno virtual con
$pipenv installSiempre que quieras emitir comandos, inicia tu entorno virtual con
$pipenv shell- sálvalo con$exitGenera todo el HTML navegando en la línea de comandos hasta el directorio de origen /Textbook y creando la compilación en ese directorio con la línea de comandos
$make html.Consulta el HTML generado en el directorio /Textbook/_build copiando la ruta completa del archivo /Textbook/_build/html/index.html y pegándolo en tu navegador.
Nota
Respecto a 1. la rama maestra del paquete que implementa disqus en Sphinx está rota, por eso usamos una instalación no estándar de pip/online. Si ya tienes instalada la versión incorrecta de Sphinx-Disqus, desinstálala con pip uninstall sphinxcontrib-disqus antes de instalar la versión funcional.
Generación local de PDF
Para comprobar los errores en la generación del PDF más rápido, puede valer la pena configurar tu máquina local para crear el PDF.
Publicación en línea
GitHub Actions compila cada pull request con Sphinx y publica automáticamente el libro de texto una vez que los cambios se fusionan en master.
Prueba tu build por primera building RST locally.
Envía una solicitud pull a Master y solicita un revisor. Cada pull request debe ser revisada por al menos otra persona.
Espera a que el flujo de trabajo Test se complete correctamente en las comprobaciones de la solicitud de tirada.
Tras la aprobación, fusiona la solicitud de pull en
master. El flujo de trabajo Documentación construirá y publicará automáticamente el libro de texto actualizado.
Importante
Si la actualización no se publica, consulta el flujo de trabajo de Documentación en Acciones de GitHub.
Pruebas en línea
Abre una solicitud pull para ejecutar la misma compilación HTML de Sphinx que usa el flujo de trabajo de publicación. La comprobación Test de la solicitud pull informa si el libro de texto se compila correctamente. Para una revisión visual, compila el libro localmente y ábrelo Textbook/_build/html/index.html en un navegador.
Breves mejores prácticas
Al escribir RST, a menudo hay muchas formas de escribir lo mismo. Casi siempre, la forma con el menor número de caracteres es la mejor. Idealmente, nunca copiar y pegar.
¿Cómo escribo RST?
RST es fácil de aprender y potente. Hay muchas hojas de trucos útiles, como esta. Cuando empieces a escribir RST, mira las hojas de trucos todo el tiempo. Úsala ctrl-f todo el tiempo para encontrar lo que necesites.
Cosas que no se cubren en la mayoría de las hojas de trucos y que son de importancia crítica:
Un documento se denomina por su título, definido entre los signos de
*****en la parte superior de la página, NO el nombre del archivo. Por eso es fundamental tener un título.¿Algo más que quieras añadir para el futuro…
Ejemplo para empezar
Este archivo está escrito en RST. ¡Puedes empezar por ahí! Solo tienes que hacer clic en «Ver fuente de la página» en la parte superior de la página.
Conversión de Markdown a RST
Idealmente, usa pandoc para hacer la conversión en línea de comandos: pandoc --from=markdown --to=rst --output=my_file.rst my_file.md. El HTML en bruto no se convertirá (porque en realidad no es markdown), y las tablas se convierten mal. Tendrás que revisar cuidadosamente cualquier página convertida con pandoc.