tutorial links español documentation markdown python-sphinx restructuredtext

documentation - links - sphinx tutorial español



Salida de Markdown para documentación basada en Sphinx (3)

Me encontré con un caso de uso, donde además de generar HTML y PDF a partir de mis fuentes de documentación basadas en Sphinx , también me gustaría generar una versión de Markdown de los archivos de origen reStructuredText .

Mi investigación preliminar no encontró ningún soporte de núcleo o extensión para esto en Sphinx . Aparte de usar pandoc manualmente o crear una nueva extensión Sphinx para la tarea, ¿existe una solución más simple / más integrada para esto?

No encontré nada que pudiera tomar los archivos reStructuredText y convertirlos a Markdown, excepto Pandoc, así que escribí un escritor personalizado para Docutils (la implementación de referencia de reStructuredText y en qué se basa Sphinx). El código está disponible en GitHub .

Tenga en cuenta que es solo una implementación inicial: maneja cualquier documento reStructuredText sin error (probado contra el documento de prueba standard.txt del repositorio de origen Docutils) pero muchas de las construcciones reStructuredText (por ejemplo, sustituciones, directivas sin formato, etc.) no son compatibles y por lo que no se incluye en la salida Markdown. Espero agregar soporte para enlaces, bloques de código, imágenes y tablas: cualquier ayuda para esto es más que bienvenida, solo adelante y bifurque el código.

Parece que para agregar otro formato de escritura / salida a Sphinx es necesario agregar un "constructor" con una extension .

Si desea usar pandoc, ¿por qué no simplemente cambia Makefile que Sphinx genera cuando ejecuta sphinx-quickstart.py por primera vez para convertir el texto reStructuredText en Markdown?
Es la solución más fácil, aunque la solución de Chris debería funcionar también si la incorporas en el Makefile.