Tenho um projeto hospedado no GitHub. Para isso, escrevi meu README usando a sintaxe Markdown para que seja bem formatado no GitHub.

Como meu projeto é em Python, também pretendo enviá-lo para PyPi . A sintaxe usada para READMEs no PyPi é reStructuredText.

Eu gostaria de evitar ter que lidar com dois READMEs contendo aproximadamente o mesmo conteúdo; então procurei um tradutor de markdown para RST (ou vice-versa), mas não consegui encontrar nenhum.

A outra solução que vejo é realizar uma marcação / HTML e, em seguida, uma tradução HTML / RST. Encontrei alguns recursos para isso aqui e aqui, então acho que deve ser possível.

Você teria alguma ideia que poderia se encaixar melhor com o que eu quero fazer?

Eu recomendaria o Pandoc , o "canivete suíço para converter arquivos de um formato de marcação para outro" (verifique o diagrama de conversões suportadas no final da página, é bastante impressionante). O Pandoc permite o markdown para reStructuredText tradução diretamente. Há também um editor online aqui que permite que você experimente, então você pode simplesmente usar o editor online para converter seus arquivos README.

Como @Chris sugeriu, você pode usar o Pandoc para converter Markdown em RST. Isso pode ser simplesmente automatizado usando o módulo pypandoc e um pouco de magia em 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=[]
)

Isso converterá automaticamente o README.md em RST para a descrição longa usando no PyPi. Quando o pypandoc não está disponível, ele apenas lê README.md sem a conversão - para não forçar outros a instalar o pypandoc quando querem apenas construir o módulo, não fazer upload para o PyPi.

Assim, você pode escrever no Markdown como de costume e não se importar mais com a bagunça do RST. ;)

Atualização de 2019

O PyPI Warehouse agora suporta renderização Markdown também! Você só precisa atualizar a configuração do seu pacote e adicionar o long_description_content_type='text/markdown'a ele. por exemplo:

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

Portanto, não há mais necessidade de manter o README em dois formatos.

Você pode encontrar mais informações sobre isso na documentação .

Resposta antiga:

A biblioteca de marcação usada pelo GitHub oferece suporte a reStructuredText. Isso significa que você pode escrever um arquivo README.rst.

Eles ainda oferecem suporte a realce de cores específicas da sintaxe usando as diretivas codee code-block( exemplo )

PyPI agora suporta Markdown para longas descrições!

Em setup.py, defina long_descriptioncomo uma string Markdown, adicione long_description_content_type="text/markdown"e certifique-se de usar ferramentas recentes ( setuptools38.6.0+, twine1.11+).

Consulte a postagem do blog de Dustin Ingram para obter mais detalhes.

Para os meus requisitos, não queria instalar o Pandoc no meu computador. Eu usei docverter. Docverter é um servidor de conversão de documentos com interface HTTP usando Pandoc para isso.

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

Você também pode estar interessado no fato de que é possível escrever em um subconjunto comum para que seu documento saia da mesma maneira quando renderizado como markdown ou renderizado como reStructuredText: https://gist.github.com/dupuy/1855764 ☺

Encontrei esse problema e resolvi-o com os dois scripts bash a seguir.

Observe que eu tenho o LaTeX empacotado no meu 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

Também é útil converter para 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 ajude

Usando a pandocferramenta sugerida por outros criei um md2rstutilitário para criar os rstarquivos. Mesmo que essa solução signifique que você tem um mde um rst, parecia ser o menos invasivo e permitiria qualquer suporte de redução futuro adicionado. Eu prefiro isso a alterar setup.pye talvez você também:

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