Ont le même fichier README à la fois en Markdown et reStructuredText

Question

J'ai un projet hébergé sur GitHub. Pour cela, j'ai écrit mon README à l'aide de la syntaxe Markdown, afin qu'elle soit bien mis en forme sur GitHub.

Comme mon projet est en Python j'ai également l'intention de le télécharger sur PyPi. La syntaxe utilisée pour les fichiers readme sur PyPi est reStructuredText.

Je voudrais éviter d'avoir à gérer deux fichiers readme contenant à peu près le même contenu; j'ai donc cherché un abattement à la taxe (ou l'inverse) traducteur, mais ne pouvais pas trouver toutes.

L'autre solution que je vois est d'effectuer une markdown/HTML puis un HTML/RST traduction. J'ai trouvé quelques ressources pour le présent , ici et ici, donc je suppose qu'il doit être possible.

Auriez-vous une idée qui pourrait s'adapter à mieux avec ce que je veux faire?

Answer 1

Je recommande Pandoc, le "couteau suisse de la conversion des fichiers d'un format de balisage dans un autre" (consultez le diagramme de conversions prises en charge au bas de la page, c'est assez impressionnant). Pandoc permet de markdown pour reStructuredText traduction directement. Il ya aussi un éditeur en ligne ici qui vous permet de l'essayer, de sorte que vous pouvez simplement utiliser l'éditeur en ligne pour convertir vos fichiers lisez-moi.

Answer 2

@Chris a suggéré, vous pouvez utiliser Pandoc pour convertir Démarque de la TVD. Cela peut simplement être automatisé à l'aide de pypandoc module et un peu de magie dans 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=[]
)

Cela va automatiquement convertir le fichier README.md à la TVD pour la longue description de l'utiliser sur PyPi. Lorsque pypandoc n'est pas disponible, alors il se contente de lire README.md sans la conversion – pour ne pas forcer les autres à installer pypandoc quand ils veulent juste de créer le module, pas de télécharger sur PyPi.

Vous pouvez donc écrire en Markdown comme d'habitude et ne se soucient pas de la TVD mess plus. ;)

Answer 3

Le Balisage de la bibliothèque utilisée par GitHub prend en charge reStructuredText. Cela signifie que vous pouvez écrire un fichier README.tvd fichier.

Ils soutiennent même syntaxe spécifique de la couleur de surbrillance à l'aide de l' code et code-block directives (Exemple)

Answer 4

À l'aide de l' pandoc outil proposé par les autres, j'ai créé un md2rst utilitaire pour créer l' rst fichiers. Même si cette solution signifie que vous avez à la fois un md et rst il semblait être le moins invasif et permettrait quel que soit l'avenir de démarque est pris en charge. Je le préfère au cours modifiant setup.py et peut-être vous serait ainsi:

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