Tener el mismo README tanto en Markdown como en reStructuredText

Tengo un proyecto alojado en GitHub. Para esto, escribí mi README usando la syntax de Markdown para tenerlo bien formateado en GitHub.

Como mi proyecto está en Python, también planeo subirlo a PyPi . La syntax utilizada para READMEs en PyPi es reStructuredText.

Me gustaría evitar tener que manejar dos README que contienen aproximadamente el mismo contenido; así que busqué una rebaja para RST (o al revés) traductor, pero no pude encontrar ninguna.

La otra solución que veo es realizar un markdown / HTML y luego una traducción de HTML / RST. Encontré algunos recursos para esto aquí y aquí, así que supongo que debería ser posible.

¿Tendría alguna idea que pudiera encajar mejor con lo que quiero hacer?

Recomendaría Pandoc , la “razor suiza para convertir archivos de un formato de marca a otro” (consulte el diagtwig de conversiones admitidas en la parte inferior de la página, es bastante impresionante). Pandoc permite a markdown reStructuredText directamente. Aquí también hay un editor en línea que te permite probarlo, así que simplemente puedes usar el editor en línea para convertir tus archivos README.

Como sugirió @Chris, puede usar Pandoc para convertir Markdown a RST. Esto puede ser simplemente automatizado usando el módulo pypandoc y algo de magia en setup.py:

 from setuptools import setup try: from pypandoc import convert read_md = lambda f: convert(f, 'rst') except ImportError: print("warning: pypandoc module not found, could not convert Markdown to RST") read_md = lambda f: open(f, 'r').read() setup( # name, version, ... long_description=read_md('README.md'), install_requires=[] ) 

Esto convertirá automáticamente el archivo README.md a RST para la descripción larga utilizando en PyPi. Cuando pypandoc no está disponible, simplemente lee README.md sin la conversión, para no forzar a otros a instalar pypandoc cuando solo quieren construir el módulo, no cargar en PyPi.

Así que puedes escribir en Markdown como siempre y no te importa el desorden de RST. 😉

Actualización 2019

¡El Almacén PyPI ahora también admite la prestación de Markdown! Solo necesita actualizar la configuración de su paquete y agregar long_description_content_type='text/markdown' a él. p.ej:

 setup( name='an_example_package', # other arguments omitted long_description=long_description, long_description_content_type='text/markdown' ) 

Por lo tanto, no es necesario mantener el README en dos formatos por más tiempo.

Puedes encontrar más información al respecto en la documentación .

Respuesta antigua:

La biblioteca de marcas utilizada por GitHub admite reStructuredText. Esto significa que puede escribir un archivo README.rst.

Incluso admiten el resaltado de color específico de la syntax mediante el code y code-block directivas de code-block ( Ejemplo )

¡PyPI ahora soporta Markdown para descripciones largas!

En setup.py , establezca long_description en una cadena Markdown, agregue long_description_content_type="text/markdown" y asegúrese de que está utilizando herramientas recientes ( setuptools 38.6.0+, twine 1.11+).

Vea la publicación del blog de Dustin Ingram para más detalles.

Para mis requisitos no quería instalar Pandoc en mi computadora. Utilicé docverter. Docverter es un servidor de conversión de documentos con una interfaz HTTP que utiliza Pandoc para esto.

 import requests r = requests.post(url='http://c.docverter.com/convert', data={'to':'rst','from':'markdown'}, files={'input_files[]':open('README.md','rb')}) if r.ok: print r.content 

Es posible que también le interese el hecho de que es posible escribir en un subconjunto común para que su documento salga de la misma manera cuando se procesa como reducción o como texto replanteado: https://gist.github.com/dupuy/1855764

Me encontré con este problema y lo resolví con los dos siguientes scripts de bash.

Tenga en cuenta que tengo LaTeX incluido en mi Markdown.

 #!/usr/bin/env bash if [ $# -lt 1 ]; then echo "$0 file.md" exit; fi filename=$(basename "$1") extension="${filename##*.}" filename="${filename%.*}" if [ "$extension" = "md" ]; then rst=".rst" pandoc $1 -o $filename$rst fi 

También es útil convertir a html. md2html:

 #!/usr/bin/env bash if [ $# -lt 1 ]; then echo "$0 file.md " exit; fi filename=$(basename "$1") extension="${filename##*.}" filename="${filename%.*}" if [ "$extension" = "md" ]; then html=".html" if [ -z $2 ]; then # if no css pandoc -s -S --mathjax --highlight-style pygments $1 -o $filename$html else pandoc -s -S --mathjax --highlight-style pygments -c $2 $1 -o $filename$html fi fi 

Espero que eso ayude

Usando la herramienta pandoc sugerida por otros, creé una utilidad md2rst para crear los rst archivos. A pesar de que esta solución significa que tiene tanto un md como un rst , parece ser el menos invasivo y permitiría agregar cualquier soporte de recargo futuro. Lo prefiero a la modificación de setup.py y tal vez usted también lo haría:

 #!/usr/bin/env python ''' Recursively and destructively creates a .rst file for all Markdown files in the target directory and below. Created to deal with PyPa without changing anything in setup based on the idea that getting proper Markdown support later is worth waiting for rather than forcing a pandoc dependency in sample packages and such. Vote for (https://bitbucket.org/pypa/pypi/issue/148/support-markdown-for-readmes) ''' import sys, os, re markdown_sufs = ('.md','.markdown','.mkd') markdown_regx = '\.(md|markdown|mkd)$' target = '.' if len(sys.argv) >= 2: target = sys.argv[1] md_files = [] for root, dirnames, filenames in os.walk(target): for name in filenames: if name.endswith(markdown_sufs): md_files.append(os.path.join(root, name)) for md in md_files: bare = re.sub(markdown_regx,'',md) cmd='pandoc --from=markdown --to=rst "{}" -o "{}.rst"' print(cmd.format(md,bare)) os.system(cmd.format(md,bare))