Ich habe ein Projekt auf GitHub gehostet. Dafür habe ich meine README mit der Markdown-Syntax geschrieben, damit sie auf GitHub gut formatiert ist.

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

Ich möchte vermeiden, dass zwei READMEs behandelt werden müssen, die ungefähr den gleichen Inhalt enthalten. 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- und dann eine HTML / RST-Übersetzung durchzuführen. Ich habe hier und hier einige Ressourcen dafür gefunden , also denke ich, dass es möglich sein sollte.

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

Ich würde Pandoc empfehlen , das "Schweizer Taschenmesser zum Konvertieren von Dateien von einem Markup-Format in ein anderes" (siehe das Diagramm der unterstützten Konvertierungen am Ende der Seite, es ist ziemlich beeindruckend). Mit Pandoc kann Markdown die Übersetzung von Text direkt reStructuredText durchführen. Hier gibt es auch einen Online-Editor , mit dem Sie es ausprobieren können. Sie können also einfach den Online-Editor verwenden, um Ihre README-Dateien zu konvertieren.

Wie von @Chris vorgeschlagen, können Sie mit Pandoc Markdown in RST konvertieren. Dies kann einfach mithilfe des Pypandoc- Moduls 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=[]
)

Dadurch wird README.md für die lange Beschreibung mit PyPi automatisch in RST konvertiert. Wenn pypandoc nicht verfügbar ist, wird nur README.md ohne Konvertierung gelesen, um andere nicht zu zwingen, pypandoc zu installieren, wenn sie nur das Modul erstellen und nicht auf PyPi hochladen möchten.

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

Update 2019

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

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

Daher muss die README-Datei nicht mehr in zwei Formaten gespeichert werden.

Weitere Informationen dazu finden Sie in der Dokumentation .

Alte Antwort:

Die von GitHub verwendete Markup- Bibliothek unterstützt reStructuredText. Dies bedeutet, dass Sie eine README.rst-Datei schreiben können.

Sie unterstützen sogar syntaxspezifische Farbhervorhebungen mit den Anweisungen codeund code-block( Beispiel )

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

In setup.py, Satz long_descriptionzu einem Markdown - String, fügen Sie long_description_content_type="text/markdown"und stellen Sie sicher sind Sie kürzlich Werkzeug (mit setuptools38.6.0+, twine1.11+).

Weitere Informationen finden Sie in Dustin Ingrams Blogbeitrag .

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 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

Möglicherweise interessiert Sie auch die Tatsache, dass es möglich ist, in eine gemeinsame Teilmenge zu schreiben, sodass Ihr Dokument beim Rendern als Markdown oder als reStructuredText auf die gleiche Weise angezeigt wird: https://gist.github.com/dupuy/1855764 ☺

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, um 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

Mit dem pandocvon anderen vorgeschlagenen Tool habe ich ein md2rstDienstprogramm zum Erstellen der rstDateien erstellt. Obwohl diese Lösung bedeutet, dass Sie sowohl eine mdals auch eine rsthaben, schien sie am wenigsten invasiv zu sein und würde jede zukünftige Markdown-Unterstützung ermöglichen. Ich ziehe es vor, mich zu verändern, setup.pyund vielleicht würdest du es 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))