python - code - Tener el mismo archivo README en Markdown y reStructuredText

readme md format

Question

Tengo un proyecto alojado en GitHub. Para esto, he escrito mi archivo README utilizando la sintaxis de Markdown para que tenga un buen formato en GitHub.

Como mi proyecto está en Python, también planeo subirlo a PyPi . La sintaxis 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é un marcador para el traductor RST (o al revés), pero no pude encontrar ninguno.

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

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

Answer 1

¡PyPI ahora admite 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 estar utilizando herramientas recientes (herramientas de setuptools 38.6.0+, twine 1.11+).

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

Answer 2

Como sugirió @Chris, puede usar Pandoc para convertir Markdown en 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 a README.md en RST para la descripción larga usando 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 subirlo a PyPi.

Entonces puede escribir en Markdown como de costumbre y ya no le importa el RST mess. ;)

Answer 3

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

Incluso admiten el resaltado de color específico de sintaxis utilizando las directivas de code-block ( Example )

Answer 4

Me encontré con este problema y lo resolví con los dos siguientes scripts 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 para convertir a html. md2html:

#!/usr/bin/env bash

if [ $# -lt 1 ]; then
  echo "$0 file.md <style.css>"
  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

Answer 5

Para mis requisitos, no quería instalar Pandoc en mi computadora. Usé docverter. Docverter es un servidor de conversión de documentos con una interfaz HTTP que usa 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

Answer 6

Recomendaría Pandoc , la "navaja suiza para convertir archivos de un formato de marcado a otro" (consulte el diagrama de conversiones compatibles en la parte inferior de la página, es bastante impresionante). Pandoc permite el descuento de la traducción reStructuredText directamente. También hay un editor en línea here que le permite probarlo, por lo que simplemente podría usar el editor en línea para convertir sus archivos README.

Answer 7

También podría estar interesado en el hecho de que es posible escribir en un subconjunto común para que su documento salga de la misma manera cuando se represente como un descuento o se represente como reStructuredText: https://gist.github.com/dupuy/1855764 ☺

Answer 8

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 un md y un rst , parece ser el menos invasivo y permitiría cualquier soporte de rebaja futuro agregado. Lo prefiero sobre la modificación de setup.py y tal vez también lo harías:

#!/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))