Worknote: Sphinx und Markdown (Sphinx revisited)

Regelmäßige Leser des Schockwellenreiters erinnern sich vielleicht daran, daß ich vor etwa zwei Jahren für einen Klienten ein Projekt »Softwaredokumentation mit Sphinx« an der Backe hatte. Doch weder meine Klienten noch ich sind mit reStructuredText richtig warm geworden und so haben wir die Dokumentation außer Haus gegeben. Ich fand es ein wenig schade, denn Sphinx hatte gerade für Python-Projekte durchaus einige Vorzüge, die das Tool aus der Menge der Dokumentations-Generatoren herausragen ließen.

Wenn nur reStructuredText nicht wäre, das zum Beispiel bei Quelltexten als erste Einrückung drei Leerzeichen verlangte, um danach – wie bei Python üblich – jede weitere Einrückung mit vier Leerzeichen vorzunehmen. Welcher Editor macht das mit?¹ Doch nun müssen die Karten neu gemischt werden, denn Sphinx kann jetzt Markdown!

Sphinx nutzt dafür den MyST-Parser, eine Python-Implementierung von CommonMark mit einigen für Dokumentationsseiten wichtigen Erweiterungen wie Fußnoten, mathematischen Formelsatz oder Addmonitions.

Zwischen dem Markdown von MyST und der Markdown-Implementierung, die MkDocs verwendet, scheint es nur wenige bis gar keine Differenzen zu geben, so daß man die verwendeten Dateien hin- und herschieben könnte (muß ich noch testen).

Ich habe momentan kein Software-Dokumentationsprojekt, aber für das nächste, das mir unterkommt, kommt Sphinx wieder in die engere Wahl. Still digging!

---

1 (Email-) Kommentar

---

Ich habe vor kurzem den MyST-Parser wieder heruntergeworfen und schreibe nun all meine Dokumente in reStructuredText, auch wenn ich davon kein großer Fan bin und war und dauernd Elemente nachschauen muss.
vscode macht das mit der Einrückung problemlos mit (Sphinx und rst sind ja auch quasi der Standardweg Code in Python zu dokumentieren, man befindet sich hier also auf einem Terrain, was viele vorher schon begangen haben). Ich weiß leider nicht mehr was der genaue Grund war… irgendwas machte Probleme und bei der Fehlersuche bin ich so weit zurückgegangen, bis ich die Markdown-Teile ersetzt hatte.
So wenig ich reStructuredText mochte, umso mehr muss ich jetzt aber sagen, dass mir das Gesamtergebnis gefällt. Manche Dinge gehen in reStructuredText auch etwas sauberer als in Markdown, weil es dort viele Formatierungsoptionen gibt (z.B. bei Code das Einstellen von Zeilennnummern, Markieren einzelner Code-Zeilen oder Formatierungsoptionen für Bilder, …). Die kann ich in MyST zwar auch mit einem rst-Block einbinden, aber das sieht dann nicht so schön aus.

– Andreas S. (Kommentieren) (#)

---

(Kommentieren)