Verwendung von Sphinx mit Markdown anstelle von RST

Ich hasse RST, aber ich liebe Sphinx. Gibt es eine Möglichkeit, wie Sphinx Markdown anstelle von reStructuredText liest?

Der "richtige" Weg, dies zu tun, wäre, einen Docutils-Parser für Markdown zu schreiben . (Plus eine Sphinx-Option zur Auswahl des Parsers.) Das Schöne daran ist die sofortige Unterstützung aller Docutils-Ausgabeformate (aber das interessiert Sie vielleicht nicht, da für die meisten bereits ähnliche Markdown-Tools vorhanden sind). Möglichkeiten, dies zu erreichen, ohne einen Parser von Grund auf neu zu entwickeln:

• Sie könnten einen "Parser" betrügen und schreiben, der Pandoc verwendet , um Markdown in RST zu konvertieren und diesen 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 einen vorhandenen Python-Markdown-Parser verwenden , mit dem Sie einen benutzerdefinierten Renderer definieren und den Knotenbaum docutils erstellen können.

• Sie könnten den vorhandenen RST-Reader verzweigen, alles herausnehmen, was für das Markdown irrelevant ist, und die verschiedenen Syntaxen ändern ( dieser Vergleich könnte helfen) ...
  BEARBEITEN: Ich empfehle diese Route nur, wenn Sie bereit sind, sie gründlich zu testen. Markdown hat bereits zu viele subtil unterschiedliche Dialekte und dies wird wahrscheinlich zu einem weiteren führen ...

UPDATE: https://github.com/sgenoud/remarkdown ist ein Markdown-Reader für Dokumente. Es wurden keine der oben genannten Verknüpfungen verwendet, sondern eine Petersilien- PEG-Grammatik verwendet, die vom Peg-Markdown inspiriert ist . Unterstützt noch keine Richtlinien.

UPDATE: https://github.com/rtfd/recommonmark und ist ein weiterer Docutils-Reader, der von ReadTheDocs nativ unterstützt wird. Abgeleitet von Remarkdown, verwendet jedoch den CommonMark-py- Parser. Unterstützt keine Direktiven, kann jedoch mehr oder weniger natürliche Markdown-Syntaxen in geeignete Strukturen konvertieren , z. B. eine Liste von Links zu einem toctree. Für andere Anforderungen können Sie mit einem ```eval_rsteingezäunten Block eine beliebige rST-Direktive einbetten.

In allen Fällen müssen Sie Erweiterungen von Markdown erfinden, um Sphinx-Anweisungen und -Rollen darzustellen . Während Sie möglicherweise nicht alle benötigen, sind einige .. toctree::davon unerlässlich.
Dies ist meiner Meinung nach der schwierigste Teil. reStructuredText vor den Sphinx-Erweiterungen war bereits umfangreicher als Markdown. Selbst stark verlängerte Abschriften wie Pandocs sind meist eine Teilmenge der rST-Funktionen. Das ist viel zu tun!

In Bezug auf die Implementierung ist es am einfachsten, ein generisches Konstrukt hinzuzufügen, um die Rolle / Direktive von docutils auszudrücken. Die offensichtlichen Kandidaten für Syntaxinspiration sind:

• Attributsyntax, die Pandoc und einige andere Implementierungen bereits für viele Inline- und Blockkonstrukte zulassen. Zum Beispiel `foo`{.method}-> `foo`:method:.
• HTML / XML. Vom <span class="method">foo</span>kludgesten Ansatz, nur docutils internes XML einzufügen!
• Eine Art YAML für Direktiven?

Eine solche generische Zuordnung ist jedoch nicht die am meisten markierte Lösung ... Derzeit sind https://groups.google.com/forum/#!topic/pandoc-discuss , https: // die aktivsten Orte, um Markdown-Erweiterungen zu diskutieren github.com/scholmd/scholmd/

Dies bedeutet auch, dass Sie einen Markdown-Parser nicht einfach wiederverwenden können, ohne ihn irgendwie zu erweitern. Pandoc wird seinem Ruf als Schweizer Taschenmesser für die Konvertierung von Dokumenten wieder gerecht, indem es benutzerdefinierte Filtes unterstützt . (Wenn ich mich dem nähern würde, würde ich versuchen, eine generische Brücke zwischen Docutils-Lesern / Transformatoren / Schriftstellern und Pandoc-Lesern / Filtern / Schriftstellern zu schlagen. Es ist mehr als Sie brauchen, aber die Auszahlung wäre viel breiter als nur Sphinx / Abschlag.)

Alternative verrückte Idee: Anstatt Markdown für Sphinx zu erweitern, erweitern Sie reStructuredText, um (meistens) eine Obermenge von Markdown zu unterstützen! Das Schöne ist, dass Sie alle Sphinx-Funktionen unverändert verwenden und dennoch die meisten Inhalte in Abschriften schreiben können.

Es gibt bereits erhebliche Syntaxüberschneidungen . Vor allem die Link-Syntax ist nicht kompatibel. Ich denke, wenn Sie RST Unterstützung für Markdown-Links und ###Header im Stil hinzufügen und die Standardrolle `backticks`in Literal ändern und möglicherweise eingerückte Blöcke in Literal ändern (RST unterstützt)> ... heutzutage Anführungszeichen), erhalten Sie etwas Verwendbares, das die meisten Markdowns unterstützt .

Sie können Markdown und reStructuredText im selben Sphinx-Projekt verwenden. Wie das geht, ist in Read The Docs kurz dokumentiert .

Installieren Sie empfohlene Markierung ( pip install recommonmark) und bearbeiten Sie 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 mit Markdown) erstellt, das zeigt, wie (und das) es funktioniert. Es verwendet CommonMark 0.5.4 und Recommonmark 0.4.0.

Dies verwendet keine Sphinx, aber MkDocs erstellt Ihre Dokumentation mit Markdown. Ich hasse auch zuerst und habe MkDocs bisher wirklich genossen.

Update: Dies wird jetzt offiziell unterstützt und in den Sphinx-Dokumenten dokumentiert .

Es sieht so aus, als hätte eine grundlegende Implementierung den Weg in die Sphinx gefunden, aber es hat sich noch nicht herumgesprochen. Siehe Github-Problemkommentar

Abhängigkeiten installieren:

pip install commonmark recommonmark

anpassen conf.py:

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

Markdown und ReST machen verschiedene Dinge.

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

Markdown bietet eine Möglichkeit, Textteile zu gravieren.

Es erscheint vernünftig, auf Ihre Markdown-Inhalte aus Ihrem Sphinx-Projekt verweisen zu wollen und RST zu verwenden, um die gesamte Informationsarchitektur und den Fluss eines größeren Dokuments zu optimieren. Lassen Sie Markdown das tun, was es tut, damit sich die Autoren auf das Schreiben von Text konzentrieren können.

Gibt es eine Möglichkeit, auf eine Markdown-Domain zu verweisen, nur um den Inhalt so zu gravieren, wie er ist? RST / Sphinx scheint sich um Funktionen gekümmert zu haben, toctreeohne sie im Markdown zu duplizieren.

Dies wird jetzt offiziell unterstützt: http://www.sphinx-doc.org/en/stable/markdown.html

Ich folgte Benis Vorschlag, Pandoc für diese Aufgabe zu verwenden. Nach der Installation konvertiert das folgende Skript alle Markdown-Dateien im Quellverzeichnis in erste Dateien, sodass Sie einfach Ihre gesamte Dokumentation in Markdown schreiben können. Hoffe das ist nützlich für andere.

#!/usr/bin/env python
import os
import subprocess

DOCUMENTATION_SOURCE_DIR = 'documentation/source/'
SOURCE_EXTENSION = '.md'
OUTPUT_EXTENSION = '.rst'

for _, __, filenames in os.walk(DOCUMENTATION_SOURCE_DIR):
    for filename in filenames:
        if filename.endswith('.md'):
            filename_stem = filename.split('.')[0]
            source_file = DOCUMENTATION_SOURCE_DIR + filename_stem + SOURCE_EXTENSION
            output_file = DOCUMENTATION_SOURCE_DIR + filename_stem + OUTPUT_EXTENSION
            command = 'pandoc -s {0} -o {1}'.format(source_file, output_file)
            print(command)
            subprocess.call(command.split(' '))

Es gibt eine Problemumgehung.
Das Skript sphinx-quickstart.py generiert ein Makefile.
Sie können Pandoc jedes Mal, wenn Sie die Dokumentation generieren möchten, einfach über das Makefile aufrufen, um Markdown in reStructuredText zu konvertieren.

Hier ist eine neue Option. MyST fügt Markdown einige Funktionen hinzu, mit denen Sphinx wie rst Dokumente erstellen kann. https://myst-parser.readthedocs.io/en/latest/

Beachten Sie die Gebäudedokumentation mit maven und eingebetteter Sphinx + MarkDown-Unterstützung durch das folgende Maven-Plugin vollständig unterstützt wird:

https://trustin.github.io/sphinx-maven-plugin/index.html

<plugin>
  <groupId>kr.motd.maven</groupId>
  <artifactId>sphinx-maven-plugin</artifactId>
  <version>1.6.1</version>
  <configuration>
    <outputDirectory>${project.build.directory}/docs</outputDirectory>
  </configuration>
  <executions>
    <execution>
      <phase>package</phase>
      <goals>
        <goal>generate</goal>
      </goals>
    </execution>
  </executions>
</plugin>