Verwenden von Sphinx mit Markdown anstelle von RST

Ich hasse RST aber liebe Sphinx. Gibt es einen Weg, dass Sphinx Markierung statt reStructuredText liest?

4 Solutions collect form web for “Verwenden von Sphinx mit Markdown anstelle von RST”

Die "richtige" Weise, das zu tun, wäre, einen docutils Parser für Abschlag zu schreiben. (Plus eine Sphinx-Option, um den Parser zu wählen.) Die Schönheit von diesem wäre sofortige Unterstützung für alle docutils Ausgabeformate (aber Sie interessieren sich vielleicht nicht, da ähnliche Markdown-Tools bereits für die meisten vorhanden sind). Wege, sich dem zu nähern, ohne einen Parser von Grund auf neu zu entwickeln:

  • Du könntest einen "Parser" betrügen und schreiben, der Pandoc benutzt, um Markdown in RST umzuwandeln und an den RST-Parser zu übergeben :-).

  • Sie können einen vorhandenen Markdown-> XML-Parser verwenden und das Ergebnis (mit XSLT?) In das docutils-Schema umwandeln.

  • Sie können einige vorhandene Python-Markdown-Parser, dass Sie definieren einen benutzerdefinierten Renderer und machen es Build Docutils Knoten Baum.

  • Du könntest den vorhandenen RST-Leser gabeln, alles, was für die Markierung irrelevant ist, auszuräumen und die verschiedenen Syntaxen zu ändern ( dieser Vergleich könnte helfen) …
    EDIT: Ich empfehle diese Route nicht, es sei denn, du bist bereit, es schwer zu testen. Markdown hat schon zu viele subtil verschiedene Dialekte und das wird wahrscheinlich noch ein …

UPDATE: https://github.com/sgenoud/remarkdown ist ein Markdown-Leser für Docutils. Es hat keine der oben genannten Verknüpfungen genommen, sondern verwendet eine Petersilie- PEG-Grammatik, die durch Peg-Markdown inspiriert wurde. Unterstützt noch keine Richtlinien.

UPDATE: https://github.com/rtfd/recommonmark und ist ein weiterer Docutils-Reader, der nativ auf ReadTheDocs unterstützt wird. Abgeleitet von remarkdown aber verwendet den CommonMark-py- Parser. Unterstützt keine Richtlinien, sondern kann mehr oder weniger natürliche Markdown-Syntaxen in entsprechende Strukturen umwandeln , zB eine Liste von Links zu einem toctree. Für andere Bedürfnisse können Sie mit einem ```eval_rst eingezäunten Block eine beliebige rST-Direktive einbetten.


In allen Fällen musst du Erweiterungen von Markdown erfinden, um Sphinx-Richtlinien und Rollen darzustellen. Während Sie vielleicht nicht alle von ihnen brauchen, sind einige wie .. toctree:: sind wesentlich.
Das denke ich ist der härteste Teil. ReStructuredText, bevor die Sphinx-Erweiterungen bereits reicher waren als Markdown. Auch stark erweiterte Markdown, wie Pandoc's , ist meist eine Teilmenge von rST-Feature-Set. Das ist viel zu decken!

Implementierung-weise, die einfachste Sache ist das Hinzufügen eines generischen Konstrukt, um jede Dokutils Rolle / Richtlinie auszudrücken. Die offensichtlichen Kandidaten für die Syntaxinspiration sind:

  • Attribut-Syntax, welche Pandok und einige andere Implementierungen bereits viele Inline- und Block-Konstrukte zulassen. Zum Beispiel `foo`{.method} -> `foo`:method:
  • HTML / XML. Von <span class="method">foo</span> zum kludgiest Ansatz von nur Einfügen von Dokumenten interne XML!
  • Irgendeine Art von YAML für Richtlinien?

Aber solch ein generisches Mapping wird nicht die meiste Abschriften-Lösung sein … Die meisten aktivsten Orte, um Markdown-Erweiterungen zu besprechen, sind https://groups.google.com/forum/#!topic/pandoc-discuss , https: // Github.com/scholmd/scholmd/

Das bedeutet auch, dass du nicht einfach einen Abschlagparser wiederverwenden kannst, ohne ihn irgendwie zu verlängern. Pandoc lebt wieder an seinem Ruf als das Schweizer Armeemesser der Dokumentenumwandlung, indem es benutzerdefinierte Filtes unterstützt . (In der Tat, wenn ich würde, um dies zu erreichen würde ich versuchen, eine generische Brücke zwischen Docutils Leser / Transformatoren / Schriftsteller und Pandoc-Leser / Filter / Schriftsteller zu bauen.Es ist mehr als Sie brauchen, aber die Auszahlung wäre viel breiter als nur Sphinx / Markierung.)


Alternative verrückte Idee: Anstatt den Markdown zu erweitern, um Sphinx zu behandeln, reStructuredText zu erweitern, um (meist) eine Obermenge von Abschlag zu unterstützen! Die Schönheit ist, dass Sie in der Lage, alle Sphinx-Funktionen wie-ist, aber in der Lage, die meisten Inhalte in Abschlag zu schreiben.

Es gibt bereits erhebliche Syntaxüberlappung ; Vor allem Link-Syntax ist nicht kompatibel. Ich denke, wenn du Unterstützung für RST für Markdown-Links und ### Header ### und die Standard- `backticks` Rolle auf wörtlich veränderst und vielleicht geänderte Blöcke ändere, um wörtlich zu verstehen (RST unterstützt > ... für Zitate heute) Du wirst etwas nutzbares bekommen, das die meisten Abschriften unterstützt.

Sie können Markdown und reStructuredText im selben Sphinx-Projekt verwenden. Wie dies zu tun ist, ist kurz auf Read the Docs dokumentiert. Installieren Sie recommonmark ( pip install recommonmark ) und bearbeiten conf.py dann conf.py :

 from recommonmark.parser import CommonMarkParser source_parsers = { '.md': CommonMarkParser, } source_suffix = ['.rst', '.md'] 

Ich habe ein kleines Beispielprojekt auf Github (serra / sphinx-with-markdown) erstellt, das zeigt, wie (und das) es funktioniert. Es verwendet CommonMark 0.5.4 und recommonmark 0.4.0.

Markdown und ReST machen verschiedene Dinge.

RST bietet ein Objektmodell für die Arbeit mit Dokumenten.

Markdown bietet eine Möglichkeit, Textstücke zu gravieren.

Es scheint vernünftig, auf Ihre Bits von Markdown-Inhalten aus Ihrem Sphinx-Projekt zu verweisen, indem Sie RST verwenden, um die gesamte Informationsarchitektur und den Fluss eines größeren Dokuments zu verteilen. Lassen Sie Markdown tun, was es tut, was es Schriftstellern erlaubt, sich auf das Schreiben von Text zu konzentrieren.

Gibt es eine Möglichkeit, auf eine Markdown-Domain zu verweisen, nur um den Inhalt zu gravieren? RST / Sphinx scheint sich um Features wie toctree gekümmert zu haben, ohne sie in toctree zu duplizieren.

Das benutzt Sphinx nicht, aber MkDocs baut deine Dokumentation mit Markdown auf. Ich hasse auch erst, und habe MkDocs bis jetzt genossen.

  • Sphinx-Dokumentenmodul-Eigenschaften
  • Verbinde Sphinx autodoc-skip-member mit meiner Funktion
  • Wie kann man Instanzattribute in sphinx doc anzeigen?
  • Kann nicht "Grammar.txt" in python-sphinx finden
  • Was ist der richtige Weg, um einen ** kwargs Parameter zu dokumentieren?
  • Verwenden von Sphinx zum automatischen Dokumentieren einer Python-Klasse, Modul
  • Substitutionen innerhalb von Links in reST / Sphinx
  • Dokumentieren von Dateien mit "from x import *"
  • Code in Autodoc docstring ausführen
  • Strukturierung der Sphinx-Dokumentation
  • Django sphinx automodule - Grundlagen
  • Python ist die beste Programmiersprache der Welt.