Tenha o mesmo README no Markdown e no reStructuredText


116

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?


21
O Github irá renderizar README.rst!
u0b34a0f6ae

Isso é novo então :) Mas bom saber, vou tentar!
jlengrand

6
Se desejar que o PyPI ofereça suporte a readmes no Markdown, comente sobre a solicitação de recurso em bitbucket.org/pypa/pypi/issue/148/support-markdown-for-readmes
Coronel Panic

Respostas:


88

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.


45
A invocação mágica é: pandoc --from=markdown --to=rst --output=README.rst README.md
Jonathan Eunice

47

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. ;)


Isso realmente não resolve o problema, pois se o usuário não tiver o pypandoc instalado (o que provavelmente não acontecerá), ele gerará um erro, pois o PyPI espera que o campo long_description seja RST. Se pypandoc não estiver disponível, você deve definir long_description como None ou uma string vazia.
Cerin de

7
Não, é necessário apenas ao enviar os metadados para PyPi (que está fazendo apenas o desenvolvedor do módulo, não os usuários). Ele não lança nenhum erro quando o usuário instala o módulo e não tem o pypandoc instalado. Eu verifiquei este caso de uso.
Jakub Jirutka

Isso também pode gerar um erro de tempo de execução. Para ficar do lado seguro, recomendo fazer try-exceptna função.
varejpsilon de

1
Perfeito! Só uma coisa - eu estava recebendo uma RuntimeError: Missing format!exceção até que mudei o lambda para read_md = lambda f: convert(f, 'rst', 'md'). A razão é (suponho) que coloquei uma string e não um arquivo (sem extensão).
frnhr

@frnhr Seu palpite está correto. O Pandoc é capaz de detectar automaticamente o formato de origem de uma extensão de arquivo, mas quando você o alimenta com uma string, você deve especificar o formato explicitamente.
Jakub Jirutka

30

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 )


6

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.


Bom saber! É interessante ver como o progresso é feito ao longo do tempo na comunidade python, observando a história desse problema :).
jlengrand

4

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

3

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


1

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


0

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))
Ao utilizar nosso site, você reconhece que leu e compreendeu nossa Política de Cookies e nossa Política de Privacidade.
Licensed under cc by-sa 3.0 with attribution required.