web-dev-qa-db-fra.com

Avoir le même README à la fois dans Markdown et reStructuredText

J'ai un projet hébergé sur GitHub. Pour cela, j'ai écrit mon README en utilisant la syntaxe Markdown afin de le mettre en forme sur GitHub.

Comme mon projet est en Python, je prévois également de le télécharger sur PyPi . La syntaxe utilisée pour les fichiers README sur PyPi est reStructuredText. 

J'aimerais éviter de devoir gérer deux fichiers README contenant à peu près le même contenu; J'ai donc cherché un traducteur pour RST (ou l'inverse), mais je n'ai pas pu en trouver. 

L'autre solution que je vois est d'effectuer une traduction HTML/HTML puis une traduction HTML/RST. J'ai trouvé des ressources pour cela ici et ici donc je suppose que cela devrait être possible.

Auriez-vous une idée qui pourrait mieux correspondre à ce que je veux faire?

pythongithubmarkdownrestructuredtextpypi
111
jlengrand

Je recommande Pandoc , le "couteau suisse qui permet de convertir des fichiers d’un format de balisage à un autre" (consultez le diagramme des conversions prises en charge en bas de page, il est assez impressionnant). Pandoc permet à Markdown de traduire directement la traduction reStructuredText. Il existe également un éditeur en ligne ici qui vous permet de l'essayer. Vous pouvez donc simplement utiliser l'éditeur en ligne pour convertir vos fichiers README.

86
Chris

Comme @Chris l'a suggéré, vous pouvez utiliser Pandoc pour convertir Markdown en RST. Ceci peut être simplement automatisé en utilisant 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 convertira automatiquement README.md en RST pour la description longue en utilisant PyPi. Lorsque pypandoc n'est pas disponible, alors il lit simplement README.md sans conversion - pour ne pas forcer les autres à installer pypandoc lorsqu'ils veulent simplement construire le module, pas pour le télécharger sur PyPi.

Vous pouvez donc écrire dans Markdown comme d’habitude sans vous soucier du fouillis de la TVD. ;)

47
Jakub Jirutka

Mise à jour 2019

PyPI Warehouse supporte maintenant le rendu de Markdown! Vous devez juste mettre à jour la configuration de votre paquet et y ajouter le long_description_content_type='text/markdown'. par exemple.:

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

Par conséquent, il n'est pas nécessaire de conserver le README dans deux formats plus longtemps.

Vous pouvez trouver plus d'informations à ce sujet dans documentation .

Ancienne réponse:

La bibliothèque Markup utilisée par GitHub prend en charge reStructuredText. Cela signifie que vous pouvez écrire un fichier README.rst.

Ils prennent même en charge la coloration colorée spécifique à la syntaxe à l'aide des directives code et code-block ( Example ) 

25
Cesar Canassa

PyPI supporte maintenant Markdown pour les descriptions longues!

Dans setup.py, définissez long_description sur une chaîne Markdown, ajoutez long_description_content_type="text/markdown" et assurez-vous d'utiliser des outils récents (setuptools 38.6.0+, twine 1.11+).

Voir Le blog de Dustin Ingram pour plus de détails.

5
Petr Viktorin

Pour mes besoins, je ne voulais pas installer Pandoc sur mon ordinateur. J'ai utilisé docverter. Docverter est un serveur de conversion de documents avec une interface HTTP utilisant Pandoc pour cela.

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
4
David Miró

Vous pouvez également être intéressé par le fait qu'il est possible d'écrire dans un sous-ensemble commun afin que votre document sorte de la même manière lorsqu'il est rendu sous forme de réduction ou sous forme de reStructuredText: https://Gist.github.com/dupuy/ 1855764

3
Zooko

J'ai rencontré ce problème et l'ai résolu avec les deux scripts bash suivants.

Notez que LaTeX est fourni avec mon 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

Il est également utile de convertir en 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

J'espère que ça aide

1
Chet

À l'aide de l'outil pandoc suggéré par d'autres personnes, j'ai créé un utilitaire md2rst pour créer les fichiers rst. Même si cette solution signifie que vous avez à la fois une md et une rst, elle semble être la moins invasive et permettrait de prendre en charge le support de démarque futur. Je préfère cela plutôt que de modifier setup.py et peut-être vous aussi:

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