Haben Sie die gleiche README sowohl in Markdown als auch in reStructuredText

116

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?

jlengrand
quelle
21
Github wird rendern README.rst!
u0b34a0f6ae
Das ist dann neu :) Aber gut zu wissen, ich werde es versuchen!
Jlengrand
6
Wenn Sie möchten, dass PyPI Readmes in Markdown unterstützt, kommentieren Sie bitte die Funktionsanforderung unter bitbucket.org/pypa/pypi/issue/148/support-markdown-for-readmes
Colonel Panic

Antworten:

88

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.

Chris
quelle
44
Die magische Anrufung ist: pandoc --from=markdown --to=rst --output=README.rst README.md
Jonathan Eunice
47

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

Jakub Jirutka
quelle
Dies löst das Problem nicht wirklich, denn wenn der Benutzer kein Pypandoc installiert hat (was wahrscheinlich nicht der Fall ist), wird ein Fehler ausgegeben, da PyPI erwartet, dass das Feld long_description RST ist. Wenn pypandoc nicht verfügbar ist, sollten Sie long_description auf None oder eine leere Zeichenfolge setzen.
Cerin
7
Nein, es wird nur benötigt, wenn die Metadaten auf PyPi hochgeladen werden (dies gilt nur für Entwickler des Moduls, nicht für Benutzer). Es wird kein Fehler ausgegeben, wenn der Benutzer das Modul installiert und pypandoc nicht installiert hat. Ich habe diesen Anwendungsfall überprüft.
Jakub Jirutka
Dies kann auch einen Laufzeitfehler auslösen. Um auf der sicheren Seite zu bleiben, empfehle ich, try-exceptin der Funktion zu tun .
Varepsilon
1
Perfekt! Nur eine Sache - ich bekam eine RuntimeError: Missing format!Ausnahme, bis ich das Lambda auf änderte read_md = lambda f: convert(f, 'rst', 'md'). Grund dafür ist (ich vermute), dass ich ihm einen String und keine Datei zugeführt habe (also keine Dateierweiterung).
Freitag,
@frnhr Deine Vermutung ist richtig. Pandoc kann das Quellformat anhand einer Dateierweiterung automatisch erkennen. Wenn Sie jedoch eine Zeichenfolge eingeben, müssen Sie das Format explizit angeben.
Jakub Jirutka
30

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 )

Cesar Canassa
quelle
6

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 .

Petr Viktorin
quelle
Schön zu hören! Es ist interessant zu sehen, wie Fortschritte in der Python-Community im Laufe der Zeit gemacht werden, wenn man sich die Geschichte dieser Ausgabe ansieht :).
Jlengrand
4

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
David Miró
quelle
3

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

Zooko
quelle
1

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

Chet
quelle
0

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))
robmuh
quelle