Ho un progetto ospitato su GitHub. Per questo ho scritto il mio README usando la sintassi Markdown in modo da averlo ben formattato su GitHub.

Dato che il mio progetto è in Python, ho intenzione di caricarlo anche su PyPi . La sintassi utilizzata per i README su PyPi è reStructuredText.

Vorrei evitare di dover gestire due README contenenti all'incirca lo stesso contenuto; quindi ho cercato un markdown per il traduttore RST (o viceversa), ma non sono riuscito a trovarne.

L'altra soluzione che vedo è eseguire un markdown / HTML e quindi una traduzione HTML / RST. Ho trovato alcune risorse per questo qui e qui, quindi immagino che dovrebbe essere possibile.

Hai qualche idea che potrebbe adattarsi meglio a quello che voglio fare?

Consiglierei Pandoc , il "coltellino svizzero per convertire file da un formato di markup a un altro" (controlla il diagramma delle conversioni supportate in fondo alla pagina, è abbastanza impressionante). Pandoc consente al markdown di reStructuredText traduzione direttamente. C'è anche un editor online qui che ti permette di provarlo, quindi puoi semplicemente usare l'editor online per convertire i tuoi file README.

Come suggerito da @Chris, puoi usare Pandoc per convertire Markdown in RST. Questo può essere semplicemente automatizzato usando il modulo pypandoc e un po 'di magia in 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=[]
)

Questo convertirà automaticamente README.md in RST per la descrizione lunga utilizzando su PyPi. Quando pypandoc non è disponibile, si legge semplicemente README.md senza la conversione - per non forzare altri a installare pypandoc quando vogliono solo creare il modulo, non caricare su PyPi.

Quindi puoi scrivere in Markdown come al solito e non preoccuparti più del pasticcio RST. ;)

Aggiornamento 2019

Il PyPI Warehouse ora supporta anche il rendering di Markdown! Devi solo aggiornare la configurazione del tuo pacchetto e aggiungervi il file long_description_content_type='text/markdown'. per esempio:

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

Pertanto, non è più necessario mantenere il README in due formati.

Puoi trovare maggiori informazioni a riguardo nella documentazione .

Vecchia risposta:

La libreria di markup utilizzata da GitHub supporta reStructuredText. Ciò significa che puoi scrivere un file README.rst.

Supportano persino l'evidenziazione del colore specifica della sintassi utilizzando le direttive codee code-block( Esempio )

PyPI ora supporta Markdown per descrizioni lunghe!

In setup.py, impostare long_descriptionsu una stringa Markdown, aggiungere long_description_content_type="text/markdown"e assicurarsi di utilizzare gli strumenti recenti ( setuptools38.6.0+, twine1.11+).

Vedi il post sul blog di Dustin Ingram per maggiori dettagli.

Per le mie esigenze non volevo installare Pandoc nel mio computer. Ho usato docverter. Docverter è un server di conversione dei documenti con un'interfaccia HTTP che utilizza Pandoc per questo.

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

Potresti anche essere interessato al fatto che è possibile scrivere in un sottoinsieme comune in modo che il tuo documento risulti allo stesso modo quando reso come markdown o reso come reStructuredText: https://gist.github.com/dupuy/1855764 ☺

Mi sono imbattuto in questo problema e l'ho risolto con i due seguenti script bash.

Nota che ho LaTeX in bundle nel mio 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

È anche utile per convertire in 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

Spero che aiuti

Utilizzando lo pandocstrumento suggerito da altri ho creato md2rstun'utilità per creare i rstfile. Anche se questa soluzione significa che hai sia un mdche un rst, sembra essere la meno invasiva e consentirebbe qualsiasi supporto per il ribasso futuro aggiunto. Lo preferisco setup.pypiuttosto che alterare e forse lo faresti anche tu:

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