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?
README.rst
!Antworten:
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.
quelle
pandoc --from=markdown --to=rst --output=README.rst README.md
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 :
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. ;)
quelle
try-except
in der Funktion zu tun .RuntimeError: Missing format!
Ausnahme, bis ich das Lambda auf änderteread_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).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: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
code
undcode-block
( Beispiel )quelle
PyPI unterstützt jetzt Markdown für lange Beschreibungen!
In
setup.py
, Satzlong_description
zu einem Markdown - String, fügen Sielong_description_content_type="text/markdown"
und stellen Sie sicher sind Sie kürzlich Werkzeug (mitsetuptools
38.6.0+,twine
1.11+).Weitere Informationen finden Sie in Dustin Ingrams Blogbeitrag .
quelle
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.
quelle
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 ☺
quelle
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.
Es ist auch nützlich, um in HTML zu konvertieren. md2html:
Ich hoffe das hilft
quelle
Mit dem
pandoc
von anderen vorgeschlagenen Tool habe ich einmd2rst
Dienstprogramm zum Erstellen derrst
Dateien erstellt. Obwohl diese Lösung bedeutet, dass Sie sowohl einemd
als auch einerst
haben, 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.py
und vielleicht würdest du es auch:quelle