webentwicklung-frage-antwort-db.com.de

Das selbe haben README sowohl in Markdown als auch in reStructuredText

Ich habe ein Projekt auf GitHub gehostet. Dafür habe ich mein README mit der Markdown-Syntax geschrieben, um es auf GitHub schön formatieren zu lassen.

Da mein Projekt in Python ist, plane ich es auch nach PyPi . Die für READMEs auf PyPi verwendete Syntax ist reStructuredText. 

Ich möchte vermeiden, dass ich zwei READMEs behandeln muss, die ungefähr den gleichen Inhalt haben. Also suchte ich nach einem Abschlag für den RST-Übersetzer (oder umgekehrt), konnte aber keinen finden. 

Die andere Lösung, die ich sehe, besteht darin, einen Markdown/HTML-Code und dann eine HTML/RST-Übersetzung durchzuführen. Ich habe einige Ressourcen für diese hier und hier gefunden, also sollte es möglich sein.

Hätten Sie eine Idee, die besser zu dem passt, was ich tun möchte?

111
jlengrand

Ich würde Pandoc empfehlen, das "Schweizer Taschenmesser zum Konvertieren von Dateien von einem Markup-Format in ein anderes" (siehe Diagramm der unterstützten Konvertierungen unten auf der Seite, es ist ziemlich beeindruckend). In Pandoc kann Markdown direkt in reStructuredText übersetzt werden. Es gibt auch einen Online-Editor here , mit dem Sie es ausprobieren können. Sie können also einfach den Online-Editor zum Konvertieren Ihrer README -Dateien verwenden.

86
Chris

Wie von @Chris vorgeschlagen, können Sie mit Pandoc Markdown in RST konvertieren. Dies kann einfach mit dem Modul pypandoc und etwas Magie in setup.py automatisiert werden: 

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=[]
)

Dies wird automatisch README.md in RST für die ausführliche Beschreibung mit PyPi konvertieren. Wenn pypandoc nicht verfügbar ist, wird README.md ohne Konvertierung gelesen - um andere Benutzer nicht zur Installation von pypandoc zu zwingen, wenn sie nur das Modul erstellen möchten, und nicht in PyPi hochladen.

So können Sie wie gewohnt in Markdown schreiben und sich nicht mehr um RST-Probleme kümmern. ;)

47
Jakub Jirutka

2019 Update

Das PyPI Warehouse unterstützt jetzt auch das Rendern von Markdown! Sie müssen lediglich Ihre Paketkonfiguration aktualisieren und den long_description_content_type='text/markdown' hinzufügen. z.B.:

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

Daher ist es nicht erforderlich, die README in zwei Formaten zu behalten.

Weitere Informationen dazu finden Sie in der Dokumentation .

Alte Antwort:

Die von GitHub verwendete Bibliothek Markup unterstützt reStructuredText. Das heißt, Sie können eine README.rst-Datei schreiben.

Sie unterstützen sogar die Syntax-spezifische Farbhervorhebung mit den Anweisungen code und code-block ( Example

25
Cesar Canassa

PyPI unterstützt jetzt Markdown für lange Beschreibungen!

Setzen Sie in setup.pylong_description auf eine Markdown-Zeichenfolge, fügen Sie long_description_content_type="text/markdown" hinzu und stellen Sie sicher, dass Sie die zuletzt verwendeten Werkzeuge verwenden (setuptools 38.6.0+, twine 1.11+).

Siehe Dustin Ingrams Blogbeitrag für weitere Details.

5
Petr Viktorin

Für meine Anforderungen wollte ich Pandoc nicht auf meinem Computer installieren. Ich habe Docverter benutzt. Docverter ist ein Dokumentkonvertierungsserver mit einer HTTP-Schnittstelle, die hierfür Pandoc verwendet.

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ó

Sie könnten auch daran interessiert sein, dass Sie in einem gemeinsamen Teilsatz schreiben können, so dass Ihr Dokument auf dieselbe Weise dargestellt wird, wenn es als Markdown oder als reStructuredText dargestellt wird: https://Gist.github.com/dupuy/ 1855764

3
Zooko

Ich bin auf dieses Problem gestoßen und habe es mit den beiden folgenden Bash-Skripten gelöst.

Beachten Sie, dass ich LaTeX in meinem Markdown gebündelt habe.

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

Es ist auch nützlich, in HTML zu konvertieren. 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

Ich hoffe das hilft

1
Chet

Mit dem von anderen vorgeschlagenen pandoc-Tool erstellte ich ein md2rst-Dienstprogramm zum Erstellen der rst-Dateien. Auch wenn diese Lösung bedeutet, dass Sie sowohl eine md als auch eine rst haben, schien sie die am wenigsten invasive zu sein und würde die zukünftige Unterstützung für das Markdown-Verfahren berücksichtigen. Ich ziehe es vor, setup.py zu ändern, und vielleicht möchten Sie auch:

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