reStructuredText-in-HTML-Umwandler

So funktioniert es

reStructuredText ist die Dokumentationssprache der Python-Welt: die README.rst eines PyPI-Pakets, mit Sphinx geschriebene Dokumentation und das CHANGELOG vieler Open-Source-Projekte verwenden sie. Wenn Sie eine solche Datei außerhalb von GitHub ansehen oder ihren Inhalt in eine Webseite übernehmen wollen, fügen Sie den Text hier ein. Ein Beispiel: Die Überschrift "Installation" in der README.rst Ihres Pakets, die nummerierten Schritte, der mit :: eingeleitete pip-Befehl und die Optionstabelle erscheinen rechts als h2, ol, pre und table; ein .. note::-Block wird zu einem div mit dem Titel "Hinweis". Die Überschriftenebene folgt der docutils-Regel: Sie ergibt sich aus der Reihenfolge, in der jedes Unterstreichungszeichen zum ersten Mal vorkommt — haben Sie = vor - verwendet, ist = die erste und - die zweite Ebene. Unterstützt werden Überschriften mit Unter- oder Überstrich, Absätze, Aufzählungen und nummerierte Listen (verschachtelt), Definitions- und Feldlisten, Zeilenblöcke, Blockzitate, Trennlinien, Literal- und Doctest-Blöcke, einfache und Gittertabellen, die Direktiven image, figure, code-block und die Hinweiskästen sowie Links über .. _name:-Ziele. Sphinx-eigene Direktiven wie toctree, contents und include werden übersprungen und in der Ergebniszeile gezählt, nicht stillschweigend verschluckt. Die Ausgabe ist HTML-Quelltext: Wählen Sie "Fragment", um ihn in eine Seite einzubetten, und "Ganze Seite", um ihn als Datei zu öffnen.

Dieses Werkzeug ist auch als rst in html umwandeln, rst zu html, restructuredtext in html konvertieren, rst datei oeffnen, rst to html, readme.rst vorschau bekannt.

Was ist reStructuredText (RST)?

reStructuredText ist die Klartext-Auszeichnungssprache, die die Python-Gemeinschaft seit 2002 verwendet; die Dateiendung ist .rst. Eine Überschrift wird mit einer Linie aus ===== oder ----- darunter geschrieben, Hervorhebung mit *Sternchen*, Code mit ``doppelten Backticks`` und ein Link nach dem Muster `Text <Adresse>`_. Von Markdown unterscheiden sie die Direktiven: Blöcke wie .. note::, .. image:: und .. code-block:: geben dem Dokument eine erweiterbare Struktur. Die README.rst-Dateien von PyPI-Paketen, mit Sphinx erzeugte Dokumentationsseiten und die Dokumentation von Python selbst sind darin geschrieben; der Standard-Umwandler ist docutils.

Was ist HTML?

HTML ist die Seitensprache, die ein Browser versteht: Sie kennzeichnet die Struktur eines Inhalts mit Tags wie <h1> für eine Überschrift, <p> für einen Absatz, <ul> für eine Liste und <table> für eine Tabelle. Dieses Werkzeug überführt jede RST-Struktur in das bedeutungsgleiche HTML-Tag; Hinweiskästen und Codeblöcke erhalten Klassennamen, damit ein Stylesheet angebunden werden kann. Die Ausgabe hat kein eigenes Aussehen (CSS), nur Struktur — in einen Blogbeitrag oder ein Content-Management-System eingefügt, übernimmt sie den Stil dieser Seite von selbst. Rohes HTML und javascript:-Adressen werden bewusst nicht durchgereicht.

Was ist der Unterschied zwischen RST und Markdown?

Beide formatieren Klartext, gehören aber zu verschiedenen Welten. Markdown ist kurz und locker: # Überschrift, **fett**, [Link](Adresse); GitHub, Foren und Notiz-Apps verwenden es, es hat viele Dialekte, und Tabellen oder Hinweiskästen gehören nicht zum Standard. reStructuredText ist strenger und reicher: Überschriften werden unterstrichen, Direktiven (.. note::, .. code-block::) und Rollen (:sup:, :ref:) machen das Dokument erweiterbar, Tabellen und Fußnoten sind Teil des Standards — deshalb bevorzugen die Python-Dokumentation und Sphinx diese Sprache. Das eine lässt sich automatisch in das andere umwandeln, aber nicht eins zu eins: Die meisten Markdown-Strukturen haben ein RST-Gegenstück, RST-Direktiven in Markdown dagegen keines.

Welche Direktiven umgewandelt und welche übersprungen werden

Die Stärke von RST sind die Direktiven (Blöcke, die mit .. name:: beginnen), und einige davon haben nur innerhalb von Sphinx eine Bedeutung. Dieses Werkzeug wandelt die Direktiven um, die Dokumentinhalt erzeugen: image und figure werden zu Bildelementen, code-block / code / sourcecode zu einem Codeblock mit Sprachklasse, und note / warning / tip / important / caution / danger / hint / attention / error zu einem Hinweiskasten, dessen Titel in der Sprache der Seite steht.

Direktiven, die zum Build-Vorgang statt zum Dokument gehören — toctree, contents, include, math, csv-table, list-table — erzeugen kein HTML; ihr Inhalt gelangt nicht in die Ausgabe, und die Ergebniszeile zählt sie als "N nicht unterstützte Direktiven übersprungen". So wissen Sie, dass ein Abschnitt fehlt, ohne die Ausgabe durchzusehen. .. raw:: html wird bewusst nicht unterstützt: Über RST-Eingaben lässt sich kein rohes HTML in eine Seite einschleusen.

Warum die Ausgabe nicht wie eine Seite 'aussieht'

Was Sie im rechten Feld sehen, ist HTML-Quelltext, keine gerenderte Seite — die Tags sind ausgeschrieben. Das ist Absicht: Die Aufgabe des Werkzeugs ist es, den Text übertragbar zu machen. Um das Ergebnis zu sehen, wählen Sie "Ganze Seite", laden die .html-Datei herunter und öffnen sie mit einem Doppelklick; der Browser zeigt sie wie jede andere Seite.

Die Ausgabe enthält keine Gestaltung (CSS); Hinweiskästen tragen die Klasse admonition, Codeblöcke Klassen wie language-python, damit Sie Ihr eigenes Stylesheet anbinden können. In Links bleiben nur http(s)-, mailto-, tel- und relative Adressen erhalten; javascript:- und data:-Adressen werden durch # ersetzt.

• HTML-Fragment → in einen Blogbeitrag, einen CMS-Editor oder eine vorhandene Seite einfügen
• Ganze Seite → als Datei speichern und im Browser öffnen, an eine E-Mail anhängen
• Liegt die Quelle als Markdown vor → das eigene Werkzeug Markdown in HTML verwenden; die beiden Syntaxen mischen sich nicht

Häufige Fragen

Wie wandle ich eine RST-Datei in HTML um?

Öffnen Sie die .rst-Datei in einem Texteditor, kopieren Sie den Inhalt und fügen Sie ihn in das linke Feld ein; das HTML entsteht sofort rechts. Zum Speichern als Datei wählen Sie "Ganze Seite" und tippen auf Herunterladen. Der Text verlässt Ihr Gerät nicht; die Umwandlung läuft im Browser.

Warum fehlen Sphinx-Direktiven wie toctree oder autodoc in der Ausgabe?

Sie sind kein Dokumentinhalt, sondern Platzhalter, die Sphinx beim Build aus anderen Dateien füllt; aus einem einzelnen Text lassen sie sich nicht erzeugen. Das Werkzeug überspringt sie, und die Ergebniszeile nennt die Zahl der übersprungenen Direktiven. Inhaltsdirektiven — Überschriften, Listen, Tabellen, Codeblöcke und Hinweiskästen — werden vollständig umgewandelt.

Warum weichen die Überschriftenebenen von meiner Erwartung ab?

In RST ist kein Zeichen fest an eine Ebene gebunden; wie docutils vergibt dieses Werkzeug die Ebenen in der Reihenfolge, in der jeder Unterstreichungsstil im Dokument zum ersten Mal auftaucht. Eine Überschrift mit Überstrich gilt als anderer Stil als dasselbe Zeichen nur als Unterstrich. Beginnt das Dokument mit = und verwendet danach -, erhalten Sie h1 und h2 in dieser Reihenfolge.

Was passiert, wenn ich Markdown einfüge?

Die #-Überschriften und [Text](Adresse)-Links von Markdown sind keine RST-Syntax; sie kommen als einfache Absätze heraus, und die Ergebniszeile meldet, dass keine Struktur gefunden wurde. Für Markdown gibt es das eigene Werkzeug Markdown in HTML. RST erkennen Sie leicht an den =====- oder -----Linien unter den Überschriften und an Direktivenzeilen, die mit .. beginnen.