PEP 287 – reStructuredText Docstring Format

Autor:: David Goodger <goodger at python.org>
Discussions-To:: Doc-SIG list
Status:: Aktiv
Typ:: Informational
Erstellt:: 25. März 2002
Post-History:: 02. April 2002
Ersetzt:: 216

Inhaltsverzeichnis

Zusammenfassung
Vorteile
Ziele
Begründung
Spezifikation
Docstring-Signifikante Merkmale
Fragen & Antworten
Urheberrecht
Danksagungen

Zusammenfassung

Wenn Klartext für Inline-Dokumentation nicht ausdrucksstark genug war, haben Python-Programmierer nach einem Format für Docstrings gesucht. Dieses PEP schlägt vor, die reStructuredText-Auszeichnungssprache als Standard-Auszeichnungssprache für strukturierte Klartext-Dokumentation in Python-Docstrings sowie für PEPs und ergänzende Dokumente zu übernehmen. reStructuredText ist eine reichhaltige und erweiterbare, aber dennoch leicht lesbare, WYSIWYG-Klartext-Auszeichnungssyntax.

Hier wird nur die Low-Level-Syntax von Docstrings behandelt. Dieses PEP befasst sich überhaupt nicht mit Docstring-Semantik oder -Verarbeitung (siehe PEP 256 für eine „Road Map zu den Docstring-PEPs“). Es ist auch kein Versuch, reine Klartext-Docstrings zu verunglimpfen, die immer legitim sein werden. Die reStructuredText-Auszeichnungssprache ist eine Alternative für diejenigen, die ausdrucksstärkere Docstrings wünschen.

Vorteile

Programmierer sind von Natur aus eine faule Rasse. Wir verwenden Code mit Funktionen, Klassen, Modulen und Subsystemen wieder. Durch seine Docstring-Syntax erlaubt uns Python, unseren Code von innen zu dokumentieren. Der „Heilige Gral“ der Python Documentation Special Interest Group (Doc-SIG) war eine Auszeichnungssyntax und ein Werkzeugsatz, um automatische Dokumentation zu ermöglichen, bei der die Docstrings von Python-Systemen im Kontext extrahiert und zu nützlichen, qualitativ hochwertigen Dokumenten für verschiedene Zwecke verarbeitet werden können.

Dokumentations-Auszeichnungssprachen haben drei Kundengruppen: die Autoren, die die Dokumente schreiben, die Softwaresysteme, die die Daten verarbeiten, und die Leser, die die Endverbraucher und die wichtigste Gruppe sind. Die meisten Auszeichnungssprachen sind für die Autoren und Softwaresysteme konzipiert; Leser sollen nur die verarbeitete Form sehen, entweder auf Papier oder über Browser-Software. ReStructuredText ist anders: Es ist so konzipiert, dass es in Quellform leicht lesbar ist, ohne Vorkenntnisse der Auszeichnungssprache. ReStructuredText ist in Klartextform vollständig lesbar, und viele der Auszeichnungsformen entsprechen dem üblichen Gebrauch (z.B. *Hervorhebung*), sodass es recht natürlich lesbar ist. Dennoch ist es reichhaltig genug, um komplexe Dokumente zu erstellen, und erweiterbar, sodass es nur wenige Grenzen gibt. Um reStructuredText-Dokumente zu schreiben, sind natürlich einige Vorkenntnisse erforderlich.

Die Auszeichnung bietet Funktionalität und Ausdrucksstärke bei gleichzeitiger Beibehaltung der leichten Lesbarkeit im Quelltext. Die verarbeitete Form (HTML usw.) macht alles für die Leser zugänglich: Inline-Live-Hyperlinks; Live-Links von und zu Fußnoten; automatische Inhaltsverzeichnisse (mit Live-Links!); Tabellen; Bilder für Diagramme usw.; angenehmer, lesbarer formatierter Text.

Der reStructuredText-Parser ist jetzt verfügbar und Teil des Docutils-Projekts. Eigenständige reStructuredText-Dokumente und PEPs können in HTML konvertiert werden; andere Ausgabeformat-Schreiber werden entwickelt und werden im Laufe der Zeit verfügbar sein. Es wird an einem Python-Quellcode-„Reader“ gearbeitet, der die automatische Dokumentation aus Docstrings implementieren wird. Autoren bestehender Auto-Dokumentationstools werden ermutigt, den reStructuredText-Parser in ihre Projekte zu integrieren oder, noch besser, sich zusammenzuschließen, um einen erstklassigen Werkzeugsatz für die Python-Standardbibliothek zu erstellen.

In naher Zukunft werden Werkzeuge verfügbar sein, die es Programmierern ermöglichen, HTML für Online-Hilfe, XML für verschiedene Zwecke und schließlich PDF, DocBook und LaTeX für gedruckte Dokumentation „kostenlos“ aus den vorhandenen Docstrings zu generieren. Die Annahme eines Standards wird zumindest den Docstring-Verarbeitungstools zugutekommen, indem sie weiteres „Erfinden des Rades“ verhindert.

Schließlich könnte PyDoc, das einzige bestehende Standard-Auto-Dokumentationstool, Unterstützung für reStructuredText erhalten. Bis dahin wird es keine Probleme mit reStructuredText-Auszeichnungen haben, da es alle Docstrings als vorformatierten Klartext behandelt.

Ziele

Dies sind die allgemein anerkannten Ziele für ein Docstring-Format, wie im Doc-SIG diskutiert

Es muss für den zufälligen Betrachter in Quellform lesbar sein.
Es muss mit jedem Standard-Texteditor leicht zu tippen sein.
Es darf keine Informationen enthalten, die durch Parsen des Moduls abgeleitet werden können.
Es muss genügend Informationen (Struktur) enthalten, damit es in jedes vernünftige Auszeichnungsformat konvertiert werden kann.
Es muss möglich sein, die gesamte Dokumentation eines Moduls in Docstrings zu schreiben, ohne sich durch die Auszeichnungssprache eingeschränkt zu fühlen.

reStructuredText erfüllt all diese Ziele und übertrifft sie sogar noch, und setzt seine eigenen, noch strengeren Ziele. Siehe Docstring-Signifikante Merkmale unten.

Die Ziele dieses PEPs sind wie folgt

reStructuredText als standardmäßiges Klartextformat für Docstrings (Inline-Dokumentation von Python-Modulen und -Paketen), PEPs, README-ähnliche Dateien und andere eigenständige Dokumente zu etablieren. Der Status „Akzeptiert“ wird durch Konsens der Python-Community und eine eventuelle BDFL-Anordnung angestrebt.
Bitte beachten Sie, dass reStructuredText als *ein* Standard vorgeschlagen wird, nicht *der einzige* Standard. Seine Verwendung wird völlig optional sein. Wer es nicht nutzen möchte, muss dies nicht tun.
Um Bedenken der Python-Community zu diesem Thema einzuholen und zu adressieren.
Zur Förderung der Unterstützung durch die Community. Solange mehrere konkurrierende Auszeichnungssprachen existieren, bleibt die Entwicklergemeinschaft zersplittert. Sobald ein Standard existiert, werden die Leute ihn zu nutzen beginnen und die Dynamik wird zwangsläufig zunehmen.
Zur Konsolidierung der Bemühungen verwandter Auto-Dokumentationsprojekte. Es ist zu hoffen, dass sich interessierte Entwickler zusammenschließen und an einer gemeinsamen/zusammengeführten/einheitlichen Implementierung arbeiten werden.

Sobald reStructuredText ein Python-Standard ist, können die Bemühungen auf Werkzeuge statt auf die Diskussion eines Standards konzentriert werden. Python benötigt einen Standard-Satz von Dokumentationswerkzeugen.

In Bezug auf PEPs können eine oder beide der folgenden Strategien angewendet werden

Die bestehende PEP-Abschnittsstruktur beibehalten (einzeilige Abschnittsüberschriften, eingerückter Haupttext). Unterabschnitte können entweder verboten oder mit reStructuredText-ähnlichen unterstrichenen Überschriften im eingerückten Haupttext unterstützt werden.
Ersetzen Sie die PEP-Abschnittsstruktur durch die reStructuredText-Syntax. Abschnittsüberschriften erfordern Unterstriche, Unterabschnitte werden sofort unterstützt, und der Haupttext muss nicht eingerückt werden (außer für Blockzitate).

Strategie (b) wird empfohlen, und ihre Implementierung ist abgeschlossen.

Unterstützung für RFC 2822-Header wurde dem reStructuredText-Parser für PEPs hinzugefügt (eindeutig in einem bestimmten Kontext: der erste zusammenhängende Block des Dokuments). Es mag erwünscht sein, konkret anzugeben, welche Über- und Unterstrichstile für PEP-Abschnittsüberschriften zulässig sind, um die Einheitlichkeit zu gewährleisten.

Begründung

Das Fehlen einer Standard-Syntax für Docstrings hat die Entwicklung von Standardwerkzeugen zur Extraktion und Konvertierung von Docstrings in Dokumente in Standardformaten (z.B. HTML, DocBook, TeX) behindert. Es gab eine Reihe von vorgeschlagenen Auszeichnungssprachen und Variationen und viele Werkzeuge, die an diese Vorschläge gebunden waren, aber ohne ein Standard-Docstring-Format haben sie keine starke Anhängerschaft gefunden und/oder sind halbfertig liegen geblieben.

Während der gesamten Existenz des Doc-SIG wurde nie ein Konsens über ein einziges Standard-Docstring-Format erzielt. Eine leichte, implizite Auszeichnungssprache wurde aus folgenden Gründen (unter anderem) gesucht

In Python-Code geschriebene Docstrings sind aus dem interaktiven Interpreter verfügbar und können „printet“ werden. Daher die Verwendung von Klartext für einfache Lesbarkeit.
Programmierer möchten ihren Docstrings Struktur hinzufügen, ohne die Lesbarkeit des reinen Docstrings zu beeinträchtigen. Unverzierter Klartext kann nicht in nützliche strukturierte Formate umgewandelt („hochübersetzt“) werden.
Explizite Auszeichnungssprachen (wie XML oder TeX) werden von Unkundigen allgemein als unlesbar angesehen.
Implizite Auszeichnungssprachen sind ästhetisch kompatibel mit der sauberen und minimalistischen Python-Syntax.

Viele alternative Auszeichnungssprachen für Docstrings wurden im Laufe der Jahre im Doc-SIG vorgeschlagen; eine repräsentative Auswahl ist unten aufgeführt. Jede wird kurz in Bezug auf die oben genannten Ziele analysiert. Bitte beachten Sie, dass dies keine exklusive Liste aller bestehenden Auszeichnungssysteme ist; es gibt viele andere Auszeichnungssprachen (Texinfo, Doxygen, TIM, YODL, AFT, …), die nicht erwähnt werden.

XML, SGML, DocBook, HTML, XHTML
XML und SGML sind explizite, wohlgeformte Metasprachen, die für alle Arten von Dokumentation geeignet sind. XML ist eine Variante von SGML. Sie werden am besten im Hintergrund verwendet, da sie für ungeübte Augen wortreich, schwer zu tippen und zu unübersichtlich sind, um sie als Quelle bequem zu lesen. DocBook, HTML und XHTML sind alles Anwendungen von SGML und/oder XML und teilen alle dieselbe grundlegende Syntax und dieselben Mängel.
TeX
TeX ist ähnlich wie XML/SGML insofern, als es explizit ist, aber nicht sehr einfach zu schreiben und für Unkundige nicht leicht zu lesen.
Perl POD
Die meisten Perl-Module werden in einem Format namens POD (Plain Old Documentation) dokumentiert. Dies ist ein einfach zu tippendes, sehr Low-Level-Format mit starker Integration in den Perl-Parser. Viele Werkzeuge wandeln POD-Dokumentation in andere Formate um: Info, HTML und Manpages, unter anderem. Die POD-Syntax ähnelt jedoch Perl selbst in Bezug auf die Lesbarkeit.
JavaDoc
Spezielle Kommentare vor Java-Klassen und -Funktionen dienen zur Dokumentation des Codes. Ein Programm, das diese extrahiert und in HTML-Dokumentation umwandelt, heißt javadoc und ist Teil der Standard-Java-Distribution. JavaDoc hat jedoch eine sehr intime Beziehung zu HTML und verwendet HTML-Tags für die meisten Auszeichnungen. Daher teilt es die Lesbarkeitsprobleme von HTML.
Setext, StructuredText
Schon früh wurden Varianten von Setext (Structure Enhanced Text), einschließlich Zope Corp. StructuredText, für die Python-Docstring-Formatierung vorgeschlagen. Im Folgenden werden diese Varianten kollektiv als „STexts“ bezeichnet. STexts haben den Vorteil, dass sie ohne spezielle Kenntnisse leicht zu lesen und relativ einfach zu schreiben sind.

Obwohl sie von einigen (auch in den meisten bestehenden Python-Auto-Dokumentationstools) verwendet wurden, sind STexts bisher nicht zum Standard geworden, weil
- STexts waren unvollständig. Da „wesentliche“ Konstrukte fehlen, die die Leute in ihren Docstrings verwenden möchten, sind STexts weniger als ideal. Beachten Sie, dass diese „wesentlichen“ Konstrukte nicht universell sind; jeder hat seine eigenen Anforderungen.
- STexts waren manchmal überraschend. Textteile wurden unerwartet als Auszeichnung interpretiert, was zu Frustration bei den Benutzern führte.
- SText-Implementierungen waren fehlerhaft.
- Die meisten STexts haben keine formale Spezifikation außer der Implementierung selbst. Eine fehlerhafte Implementierung bedeutete eine fehlerhafte Spezifikation und umgekehrt.
- Es gab keinen Mechanismus, um die SText-Auszeichnungsregeln zu umgehen, wenn ein Auszeichnungszeichen in einem Nicht-Auszeichnungskontext verwendet wurde. Mit anderen Worten, keine Möglichkeit, Auszeichnungen zu maskieren.

Befürworter von impliziten STexts haben sich energisch gegen Vorschläge für explizite Auszeichnungen (XML, HTML, TeX, POD usw.) ausgesprochen, und die Debatten dauerten seit 1996 oder früher an und ab.

reStructuredText ist eine vollständige Überarbeitung und Neuinterpretation der SText-Idee, die alle oben genannten Probleme adressiert.

Spezifikation

Die Spezifikation und Benutzerdokumentation für reStructuredText ist ziemlich umfangreich. Anstatt sie hier zu wiederholen oder zusammenzufassen, werden Links zu den Originalen bereitgestellt.

Schauen Sie sich zuerst Eine reStructuredText-Einführung an, eine kurze und sanfte Einführung. Die Schnelle reStructuredText-Referenz fasst alle Auszeichnungskonstrukte kurz zusammen. Für vollständige und umfassende Details konsultieren Sie bitte die folgenden Dokumente

Zusätzlich erklärt Probleme mit StructuredText viele Auszeichnungsentscheidungen, die in Bezug auf StructuredText getroffen wurden, und Eine Aufzeichnung von reStructuredText-Syntaxalternativen dokumentiert unabhängig getroffene Auszeichnungsentscheidungen.

Docstring-Signifikante Merkmale

Ein Mechanismus zur Maskierung von Auszeichnungen.
Backslashes (\) werden verwendet, um Zeichen der Auszeichnungssprache zu maskieren, wenn sie für Nicht-Auszeichnungszwecke benötigt werden. Die Regeln für die Erkennung von Inline-Auszeichnungen wurden jedoch so konstruiert, dass die Notwendigkeit von Backslash-Maskierungen minimiert wird. Zum Beispiel, obwohl Sternchen für *Hervorhebung* verwendet werden, werden in Nicht-Auszeichnungskontexten wie „*“ oder „(*)“ oder „x * y“ die Sternchen nicht als Auszeichnung interpretiert und bleiben unverändert. Für viele Nicht-Auszeichnungszwecke von Backslashes (z.B. Beschreibung regulärer Ausdrücke) sind Inline-Literale oder Literalblöcke anwendbar; siehe nächster Punkt.
Auszeichnung zum Einbinden von Python-Quellcode und Python-interaktiven Sitzungen: Inline-Literale, Literalblöcke und Doctest-Blöcke.
Inline-Literale verwenden doppelte Anführungszeichen, um Programm-I/O oder Code-Schnipsel zu kennzeichnen. Innerhalb von Inline-Literalen erfolgt keine Auszeichnungsinterpretation (einschließlich Backslash-Maskierungsinterpretation [\]).

Literalblöcke (wörtlicher Text auf Blockebene, wie Codeausschnitte oder ASCII-Grafiken) sind eingerückt und werden durch einen Doppelpunkt („::“) am Ende des vorhergehenden Absatzes gekennzeichnet (direkt hier –>)
```
if literal_block:
    text = 'is left as-is'
    spaces_and_linebreaks = 'are preserved'
    markup_processing = None
```
Doctest-Blöcke beginnen mit „>>> „ und enden mit einer Leerzeile. Weder Einrückung noch Literalblock-Doppelpunkte sind erforderlich. Zum Beispiel
```
Here's a doctest block:

>>> print 'Python-specific usage examples; begun with ">>>"'
Python-specific usage examples; begun with ">>>"
>>> print '(cut and pasted from interactive sessions)'
(cut and pasted from interactive sessions)
```

Auszeichnung, die einen Python-Bezeichner isoliert: interpretierter Text.

Text, der in einfache Anführungszeichen eingeschlossen ist, wird als „interpretierter Text“ erkannt, dessen Interpretation anwendungsabhängig ist. Im Kontext eines Python-Docstrings ist die Standardinterpretation von interpretiertem Text als Python-Bezeichner. Der Text wird mit einem Hyperlink markiert, der mit der Dokumentation für den angegebenen Bezeichner verknüpft ist. Suchregeln sind dieselben wie in Python selbst: LGB-Namensraum-Suchen (lokal, global, builtin). Die „Rolle“ des interpretierten Textes (Identifizierung einer Klasse, eines Moduls, einer Funktion usw.) wird implizit aus der Namensraumsuchung ermittelt. Zum Beispiel

class Keeper(Storer):

    """
    Keep data fresher longer.

    Extend `Storer`.  Class attribute `instances` keeps track
    of the number of `Keeper` objects instantiated.
    """

    instances = 0
    """How many `Keeper` objects are there?"""

    def __init__(self):
        """
        Extend `Storer.__init__()` to keep track of
        instances.  Keep count in `self.instances` and data
        in `self.data`.
        """
        Storer.__init__(self)
        self.instances += 1

        self.data = []
        """Store data in a list, most recent last."""

    def storedata(self, data):
        """
        Extend `Storer.storedata()`; append new `data` to a
        list (in `self.data`).
        """
        self.data = data

Jeder Teil des interpretierten Textes wird gemäß dem lokalen Namensraum des Blocks durchsucht, der seinen Docstring enthält.

Auszeichnung, die einen Python-Bezeichner isoliert und seinen Typ angibt: interpretierter Text mit Rollen.
Obwohl der Python-Quellkontext-Reader so konzipiert ist, dass keine expliziten Rollen erforderlich sind, können sie verwendet werden. Um Bezeichner explizit zu klassifizieren, wird die Rolle zusammen mit dem Bezeichner in Präfix- oder Suffixform angegeben
```
Use :method:`Keeper.storedata` to store the object's data in
`Keeper.data`:instance_attribute:.
```
Die gewählte Syntax für Rollen ist wortreich, aber notwendigerweise so (wenn jemand eine bessere Alternative hat, bitte posten Sie sie an den Doc-SIG). Die Absicht der Auszeichnung ist, dass wenig Notwendigkeit besteht, explizite Rollen zu verwenden; ihre Verwendung soll auf ein absolutes Minimum beschränkt werden.
Auszeichnung für „getaggte Listen“ oder „Beschriftungslisten“: Feldlisten.
Feldlisten stellen eine Zuordnung von Feldnamen zu Feldern dar. Diese werden meist für Erweiterungssyntax verwendet, wie z.B. „bibliographische Feldlisten“ (die Dokumentenmetadaten wie Autor, Datum und Version darstellen) und Erweiterungsattribute für Direktiven (siehe unten). Sie können zur Implementierung von Methodologien (Docstring-Semantik) verwendet werden, wie z.B. zur Identifizierung von Parametern, ausgelösten Ausnahmen usw.; eine solche Verwendung liegt außerhalb des Geltungsbereichs dieses PEPs.

Eine modifizierte RFC 2822-Syntax wird verwendet, mit einem Doppelpunkt *vor* sowie *nach* dem Feldnamen. Feldbereiche sind ebenfalls vielseitiger; sie können mehrere Feldbereiche enthalten (sogar verschachtelte Feldlisten). Zum Beispiel
```
:Date: 2002-03-22
:Version: 1
:Authors:
    - Me
    - Myself
    - I
```
Die Standard-RFC 2822-Header-Syntax kann für dieses Konstrukt nicht verwendet werden, da sie mehrdeutig ist. Ein Wort gefolgt von einem Doppelpunkt am Anfang einer Zeile ist in geschriebenem Text üblich.
Erweiterbarkeit der Auszeichnung: Direktiven und Substitutionen.
Direktiven werden als Erweiterungsmechanismus für reStructuredText verwendet, eine Möglichkeit, Unterstützung für neue Blockebenen-Konstrukte hinzuzufügen, ohne neue Syntax hinzuzufügen. Direktiven für Bilder, Mahnungen (Hinweis, Vorsicht usw.) und die Generierung von Inhaltsverzeichnissen (unter anderem) wurden implementiert. Hier ist zum Beispiel, wie ein Bild platziert wird
```
.. image:: mylogo.png
```
Substitutionsdefinitionen ermöglichen es, die Leistung und Flexibilität von Blockebenen-Direktiven für Inline-Text freizugeben. Zum Beispiel
```
The |biohazard| symbol must be used on containers used to
dispose of medical waste.

.. |biohazard| image:: biohazard.png
```

Abschnittsstruktur-Auszeichnung.

Abschnittsüberschriften in reStructuredText werden durch Unterstreichungen (und möglicherweise Überstreichungen) anstatt durch Einrückungen verziert. Zum Beispiel

This is a Section Title
=======================

This is a Subsection Title
--------------------------

This paragraph is in the subsection.

This is Another Section Title
=============================

This paragraph is in the second section.

Fragen & Antworten

Ist reStructuredText reichhaltig genug?
Ja, für die meisten Leute. Wenn ihm ein Konstrukt fehlt, das für eine bestimmte Anwendung benötigt wird, kann es über den Direktivenmechanismus hinzugefügt werden. Wenn ein nützliches und gängiges Konstrukt übersehen wurde und eine entsprechend lesbare Syntax gefunden werden kann, kann es zur Spezifikation und zum Parser hinzugefügt werden.
Ist reStructuredText *zu* reichhaltig?
Für bestimmte Anwendungen oder Einzelpersonen vielleicht. Im Allgemeinen nein.

Seit Anbeginn hat sich bei jedem Vorschlag für eine Docstring-Auszeichnungssprache im Doc-SIG jemand über fehlende Unterstützung für dieses oder jenes Konstrukt beschwert. Die Antwort war oft etwas wie: „Wir sprechen hier von Docstrings, und Docstrings sollten keine komplexe Auszeichnung haben.“ Das Problem ist, dass ein Konstrukt, das einer Person überflüssig erscheint, für eine andere Person absolut unerlässlich sein kann.

reStructuredText verfolgt den entgegengesetzten Ansatz: Es bietet einen reichhaltigen Satz von impliziten Auszeichnungskonstrukten (plus einen generischen Erweiterungsmechanismus für explizite Auszeichnung), der für alle Arten von Dokumenten geeignet ist. Wenn der Satz von Konstrukten für eine bestimmte Anwendung zu reichhaltig ist, können die ungenutzten Konstrukte entweder aus dem Parser entfernt werden (über anwendungsspezifische Überschreibungen) oder einfach per Konvention weggelassen werden.
Warum nicht Einrückung für die Abschnittsstruktur verwenden, wie StructuredText es tut? Ist das nicht „Pythonischer“?
Guido van Rossum schrieb am 13.06.2001 in einem Doc-SIG-Post Folgendes

Ich halte die Verwendung von Einrückungen zur Angabe von Abschnittsgliederungen immer noch für falsch. Wenn man sich ansieht, wie echte Bücher und andere gedruckte Publikationen gestaltet sind, wird man feststellen, dass Einrückungen häufig verwendet werden, aber meist auf der Ebene innerhalb des Abschnitts. Einrückungen können verwendet werden, um Listen, Tabellen, Zitate, Beispiele und Ähnliches abzugrenzen. (Das Argument, dass Docstrings anders sind, weil sie eine Eingabe für einen Textformatierer sind, ist falsch: Der ganze Sinn ist, dass sie auch ohne Verarbeitung lesbar sind.)
Ich weise das Argument zurück, dass die Verwendung von Einrückungen Pythonisch ist: Text ist kein Code, und es gelten unterschiedliche Traditionen und Konventionen. Menschen präsentieren Text seit über 30 Jahrhunderten zur Lesbarkeit. Lassen Sie uns nicht unnötig innovativ sein.

Siehe Abschnittsstruktur per Einrückung in Probleme mit StructuredText für weitere Ausführungen.
Warum reStructuredText für PEPs verwenden? Was ist falsch am bestehenden Standard?
Der bestehende Standard für PEPs ist in Bezug auf die allgemeine Ausdrucksstärke sehr begrenzt, und die Referenzierung ist für eine so reichhaltige Dokumentenart besonders mangelhaft. PEPs werden derzeit in HTML konvertiert, aber die Ergebnisse (hauptsächlich Monospace-Text) sind wenig ansprechend, und das meiste Potenzial von HTML (insbesondere Inline-Hyperlinks) bleibt ungenutzt.

Die Standardisierung von reStructuredText als Auszeichnungssprache für PEPs wird eine viel reichhaltigere Ausdrucksweise ermöglichen, einschließlich der Unterstützung für Abschnittsstruktur, Inline-Auszeichnungen, Grafiken und Tabellen. In mehreren PEPs gibt es ASCII-Grafikdiagramme, die das Einzige sind, was Klartextdokumente unterstützen können. Da PEPs in HTML-Form verfügbar sind, wäre die Möglichkeit, richtige Diagramme einzufügen, sofort nützlich.

Die aktuellen PEP-Praktiken erlauben Referenzmarkierungen in der Form „[1]“ im Text, und die Fußnoten/Referenzen selbst werden in einem Abschnitt am Ende des Dokuments aufgeführt. Derzeit gibt es keine Hyperlinks zwischen der Referenzmarkierung und der Fußnote/Referenz selbst (es wäre möglich, dies zu pep2html.py hinzuzufügen, aber die „Auszeichnung“ wäre mehrdeutig und Fehler wären unvermeidlich). Ein PEP mit vielen Referenzen (wie diesem ;-) erfordert viel Hin- und Herblättern. Beim Überarbeiten eines PEPs werden oft neue Referenzen hinzugefügt oder ungenutzte gelöscht. Es ist mühsam, die Referenzen neu zu nummerieren, da dies an zwei Stellen geschehen muss und kaskadierende Effekte haben kann (fügen Sie eine einzige neue Referenz 1 ein, und jede andere Referenz muss neu nummeriert werden; das Hinzufügen neuer Referenzen am Ende ist suboptimal). Es ist leicht, dass Referenzen aus dem Takt geraten.

PEPs verwenden Referenzen für zwei Zwecke: einfache URL-Referenzen und Fußnoten. reStructuredText unterscheidet zwischen den beiden. Ein PEP könnte Referenzen wie diese enthalten
```
Abstract

    This PEP proposes adding frungible doodads [1] to the core.
    It extends PEP 9876 [2] via the BCA [3] mechanism.

...

References and Footnotes

    [1] http://www.example.org/

    [2] PEP 9876, Let's Hope We Never Get Here
        http://peps.python.org/pep-9876/

    [3] "Bogus Complexity Addition"
```
Referenz 1 ist eine einfache URL-Referenz. Referenz 2 ist eine Fußnote, die Text und eine URL enthält. Referenz 3 ist eine Fußnote, die nur Text enthält. Umgeschrieben mit reStructuredText könnte dieses PEP so aussehen
```
Abstract
========

This PEP proposes adding `frungible doodads`_ to the core.  It
extends PEP 9876 [#pep9876]_ via the BCA [#]_ mechanism.

...

References & Footnotes
======================

.. _frungible doodads: http://www.example.org/

.. [#pep9876] PEP 9876, Let's Hope We Never Get Here

.. [#] "Bogus Complexity Addition"
```
URLs und Fußnoten können bei Bedarf nahe ihren Referenzen definiert werden, was die Lesbarkeit im Quelltext erleichtert und die PEPs leichter zu überarbeiten macht. Der Abschnitt „Referenzen und Fußnoten“ kann mit einem Dokumentenbaum-Transformationsprozess automatisch generiert werden. Fußnoten aus dem gesamten PEP werden gesammelt und unter einer Standardüberschrift angezeigt. Wenn URL-Referenzen ebenfalls explizit (in Zitationsform) geschrieben werden sollen, könnte ein weiterer Baum-Transformationsprozess verwendet werden.

URL-Referenzen können benannt werden („frungible doodads“) und von mehreren Stellen im Dokument ohne zusätzliche Definitionen referenziert werden. Wenn sie in HTML konvertiert werden, werden Referenzen durch Inline-Hyperlinks (HTML <a>-Tags) ersetzt. Die beiden Fußnoten werden automatisch nummeriert, sodass sie immer synchron bleiben. Die erste Fußnote enthält auch einen internen Referenznamen, „pep9876“, was die Verbindung zwischen Referenz und Fußnote im Quelltext erleichtert. Benannte Fußnoten können mehrfach referenziert werden, wobei die Nummerierung konsistent bleibt.

Die Fußnote „#pep9876“ könnte auch in Form einer Zitation geschrieben werden
```
It extends PEP 9876 [PEP9876]_ ...

.. [PEP9876] PEP 9876, Let's Hope We Never Get Here
```
Fußnoten werden nummeriert, während Zitate Text für ihre Referenzen verwenden.
Wäre es nicht besser, die Docstring- und PEP-Vorschläge getrennt zu halten?
Der PEP-Auszeichnungsvorschlag kann entfernt werden, wenn entschieden wird, dass kein Bedarf an PEP-Auszeichnungen besteht, oder er kann zu einem separaten PEP gemacht werden. Wenn akzeptiert, werden PEP 1, PEP Zweck und Richtlinien, und PEP 9, Beispiel-PEP-Vorlage aktualisiert.

Es erscheint natürlich, einen einzigen konsistenten Auszeichnungsstandard für alle Verwendungen von strukturiertem Klartext in Python zu übernehmen und ihn an einer Stelle vorzuschlagen.
Das bestehende pep2html.py-Skript konvertiert das bestehende PEP-Format in HTML. Wie werden die neuen PEPs in HTML konvertiert?
Eine neue Version von pep2html.py mit integrierter reStructuredText-Analyse wurde abgeschlossen. Das Docutils-Projekt unterstützt PEPs mit einer „PEP Reader“-Komponente, einschließlich aller Funktionen von pep2html.py (automatische Erkennung von PEP- und RFC-Referenzen, E-Mail-Maskierung usw.).
Wer wird die bestehenden PEPs in reStructuredText konvertieren?
PEP-Autoren oder Freiwillige können bestehende PEPs konvertieren, wenn sie möchten, aber es besteht keine Verpflichtung dazu. Die reStructuredText-basierten PEPs werden neben dem alten PEP-Standard existieren. Das in Antwort 6 erwähnte pep2html.py verarbeitet beide Standards.
Warum reStructuredText für README und andere ergänzende Dateien verwenden?
Die Argumentation für PEPs in Antwort 4 gilt auch für README- und andere ergänzende Dateien. Durch die Übernahme einer Standard-Auszeichnungssprache können diese Dateien in attraktive, Querverweise enthaltende HTML-Dokumente konvertiert und auf python.org veröffentlicht werden. Entwickler anderer Projekte können diese Einrichtung auch für ihre eigene Dokumentation nutzen.
Wird die oberflächliche Ähnlichkeit mit bestehenden Auszeichnungskonventionen nicht zu Problemen führen und dazu, dass Leute ungültige Auszeichnungen schreiben (und es nicht bemerken, weil der Klartext natürlich aussieht)? Wie fehlerverzeihend ist reStructuredText bei „nicht ganz richtiger“ Auszeichnung?
Es wird einige Fehltritte geben, wie sie beim Übergang von einer Programmiersprache zu einer anderen auftreten. Wie bei jeder Sprache wächst die Kompetenz mit der Erfahrung. Glücklicherweise ist reStructuredText in der Tat eine sehr kleine Sprache.

Wie bei jeder Syntax gibt es die Möglichkeit von Syntaxfehlern. Es wird erwartet, dass ein Benutzer das Verarbeitungssystem über seine Eingaben laufen lässt und die Ausgabe auf Korrektheit überprüft.

Im strengen Sinne ist der reStructuredText-Parser sehr unnachgiebig (wie es sein sollte; „Wenn es Mehrdeutigkeiten gibt, weise die Versuchung ab zu raten“ gilt für das Parsen von Auszeichnungen ebenso wie für Computersprachen). Hier ist Ziel 3 aus Eine Einführung in reStructuredText

Eindeutig. Die Regeln für Auszeichnungen dürfen nicht offen für Interpretationen sein. Für jede gegebene Eingabe sollte es genau eine mögliche Ausgabe geben (einschließlich Fehlerausgabe).

Obwohl unnachgiebig, versucht der Parser gleichzeitig, hilfreich zu sein, indem er nützliche Diagnoseausgaben („system messages“) erzeugt. Der Parser meldet Probleme und gibt deren Schweregrad an (von am wenigsten zu am meisten: debug, info, warning, error, severe). Der Benutzer oder die Client-Software kann über Berichtsschwellenwerte entscheiden; sie können niedrigstufige Probleme ignorieren oder hochstufige Probleme verursachen, um die Verarbeitung sofort zu stoppen. Probleme werden während des Parsens sowie in der Ausgabe gemeldet, oft mit bidirektionalen Links zwischen der Quelle des Problems und der Systemmeldung, die es erklärt.
Werden die Docstrings in den Python-Standardbibliotheksmodulen in reStructuredText konvertiert?
Nein. Die Referenzdokumentation der Python-Bibliothek wird separat vom Quellcode gepflegt. Docstrings in der Python-Standardbibliothek sollten nicht versuchen, die Referenzdokumentation der Bibliothek zu duplizieren. Die aktuelle Richtlinie für Docstrings in der Python-Standardbibliothek ist, dass sie nicht mehr als prägnante Hinweise sein sollten, einfach und ohne Auszeichnungen (obwohl viele *ad-hoc*-implizite Auszeichnungen enthalten).
Ich möchte alle meine Zeichenketten in Unicode schreiben. Wird etwas kaputt gehen?
Der Parser unterstützt Unicode vollständig. Docutils unterstützt beliebige Eingabe- und Ausgabekodierungen.
Warum braucht die Community ein neues Design für strukturierte Texte?
Die bestehenden Designs für strukturierte Texte sind aus den unter „Begründung“ genannten Gründen mangelhaft. reStructuredText zielt darauf ab, eine vollständige Auszeichnungssyntax zu sein, innerhalb der Grenzen des Mediums „lesbarer Klartext“.
Was ist falsch an bestehenden Dokumentationsmethoden?
Welche bestehenden Methoden? Für Python-Docstrings gibt es **kein** offizielles Standard-Auszeichnungsformat, geschweige denn eine Dokumentationsmethode ähnlich wie JavaDoc. Die Frage der Methodik liegt auf einer viel höheren Ebene als die Syntax (die dieses PEP behandelt). Sie ist potenziell viel kontroverser und schwieriger zu lösen und wird bewusst aus dieser Diskussion ausgeschlossen.

Urheberrecht

Dieses Dokument wurde gemeinfrei erklärt.

Danksagungen

Einige Texte sind von PEP 216, Docstring-Format, von Moshe Zadka übernommen.

Besonderer Dank geht an alle aktuellen und früheren Mitglieder des Python Doc-SIG.

Quelle: https://github.com/python/peps/blob/main/peps/pep-0287.rst

Zuletzt geändert: 2025-02-01 08:59:27 GMT