reStructuredText für Python-Dokumentation

Konvertieren Sie Markdown in RST für Sphinx und Python-Projekte

reStructuredText (RST) ist das Standard-Dokumentationsformat für Python-Projekte mit Sphinx. Während Markdown großartig zum Schreiben ist, bietet RST leistungsstarke Funktionen für technische Dokumentation. Durch die Konvertierung von Markdown in RST können Sie schnell in Markdown schreiben und in bestehende Python-Dokumentations-Workflows integrieren.

Warum in RST konvertieren?

Sphinx-Kompatibilität – RST ist das native Format von Sphinx
Python-Ökosystem – Die meiste Python-Dokumentation verwendet RST
Querverweise – RST unterstützt robuste Verlinkung zwischen Dokumenten
Erweiterungen – Zugriff auf das leistungsstarke Erweiterungsökosystem von Sphinx
Read the Docs – Direkte Integration mit RTD-Hosting

So funktioniert es

Wenn Sie Markdown in RST konvertieren, erhalten Sie korrekte RST-Syntax:

Einleitung
==========

Dies ist ein Absatz mit **fettem** und *kursivem* Text.

* Erster Punkt
* Zweiter Punkt

Code-Beispiel
-------------

.. code-block:: python

   def greet(name):
       return f"Hello, {name}!"

In RST konvertieren

Markdown-zu-RST-Zuordnung

Markdown	RST-Ausgabe
`# Überschrift`	Unterstrichen mit `=====`
`## Unterüberschrift`	Unterstrichen mit `-----`
`fett`	`fett`
`kursiv`	`kursiv`
`Code`	``Code``
`[Text](URL)`	`Text <URL>`_
Codeblöcke	`.. code-block::`

RST mit Sphinx verwenden

Grundlegender Workflow

Inhalte in Markdown für Geschwindigkeit schreiben
In RST mit Markdown2ANY konvertieren
RST-spezifische Funktionen hinzufügen (Direktiven, Querverweise)
Mit Sphinx erstellen: sphinx-build -b html source/ build/

RST-Funktionen hinzufügen

Nach der Konvertierung können Sie Ihr RST mit Sphinx-Direktiven erweitern:

.. note::
   Dies ist eine Hinweis-Admonition.

.. warning::
   Dies ist eine Warnung.

.. seealso::
   :doc:`anderes-dokument`

Häufige Anwendungsfälle

API-Dokumentation

Konvertieren Sie README-Dateien und Anleitungen in RST, um sie mit autodoc-generierten API-Referenzen zu integrieren.

Tutorials

Schreiben Sie Tutorials in Markdown, konvertieren Sie in RST und fügen Sie dann Querverweise zur API-Dokumentation hinzu.

Mitwirkungsleitfäden

Erstellen Sie Mitwirkungsdokumentation, die zum Format der restlichen Projektdokumentation passt.

RST-spezifische Funktionen

Nach der Konvertierung können Sie RST-Funktionen hinzufügen, die Markdown nicht unterstützt:

Admonitions – Hinweis-, Warnung-, Tipp-, Gefahr-Boxen
Querverweise – Verlinkung zwischen Dokumenten und Abschnitten
Rollen – Semantisches Markup wie :func:, :class:
Direktiven – Benutzerdefinierte Inhaltsblöcke
Toctrees – Dokumenthierarchien