PEP 256 – Docstring Processing System Framework

Autor:: David Goodger <goodger at python.org>
Discussions-To:: Doc-SIG list
Status:: Abgelehnt
Typ:: Standards Track
Erstellt:: 01-Jun-2001
Post-History:: 13-Jun-2001

Inhaltsverzeichnis

Ablehnungsbescheid
Zusammenfassung
Road Map to the Docstring PEPs
Begründung
- PyDoc & Other Existing Systems
Spezifikation
Project Web Site
Urheberrecht
Danksagungen

Ablehnungsbescheid

This proposal seems to have run out of steam.

Python lendest sich für Inline-Dokumentation. Mit seiner eingebauten Docstring-Syntax ist eine begrenzte Form von Literate Programming in Python einfach zu realisieren. Allerdings gibt es keine zufriedenstellenden Standardwerkzeuge zur Extraktion und Verarbeitung von Python-Docstrings. Das Fehlen eines Standard-Toolsets ist eine signifikante Lücke in Pythons Infrastruktur; dieser PEP zielt darauf ab, diese Lücke zu füllen.

Die Probleme rund um die Docstring-Verarbeitung waren umstritten und schwer zu lösen. Dieser PEP schlägt ein generisches Docstring Processing System (DPS) Framework vor, das die Komponenten (Programm und konzeptionell) trennt und die Lösung einzelner Probleme entweder durch Konsens (eine Lösung) oder durch Divergenz (viele) ermöglicht. Es fördert Standard-Schnittstellen, die es ermöglichen, eine Vielzahl von Plug-in-Komponenten (Input Context Reader, Markup Parser und Output Format Writer) zu verwenden.

Die Konzepte eines DPS-Frameworks werden unabhängig von Implementierungsdetails dargestellt.

Road Map to the Docstring PEPs

Es gibt viele Aspekte bei der Docstring-Verarbeitung. Die „Docstring PEPs“ haben die Probleme aufgeteilt, um jedes davon isoliert oder so nah wie möglich zu behandeln. Die einzelnen Aspekte und zugehörigen PEPs sind wie folgt:

Docstring-Syntax. PEP 287, „reStructuredText Docstring Format“, schlägt eine Syntax für Python-Docstrings, PEPs und andere Verwendungen vor.
Docstring-Semantik besteht aus mindestens zwei Aspekten:
- Konventionen: die High-Level-Struktur von Docstrings. Behandelt in PEP 257, „Docstring Conventions“.
- Methodologie: Regeln für den informativen Inhalt von Docstrings. Nicht behandelt.
Verarbeitungsmechanismen. Dieser PEP (PEP 256) skizziert die High-Level-Probleme und die Spezifikation eines abstrakten Docstring Processing Systems (DPS). PEP 258, „Docutils Design Specification“, ist ein Überblick über das Design und die Implementierung eines unter Entwicklung befindlichen DPS.
Output-Stile: Entwickler möchten, dass die aus ihrem Quellcode generierte Dokumentation gut aussieht, und es gibt viele verschiedene Ideen darüber, was das bedeutet. PEP 258 berührt „Stylist Transforms“. Dieser Aspekt der Docstring-Verarbeitung muss noch vollständig erforscht werden.

Durch die Trennung der Probleme können wir leichter Konsens erzielen (kleinere Auseinandersetzungen ;-)) und Abweichungen leichter akzeptieren.

Begründung

Es gibt Standard-Inline-Dokumentationssysteme für einige andere Sprachen. Zum Beispiel hat Perl POD („Plain Old Documentation“) und Java hat Javadoc, aber keines davon passt zum Pythonic Way. POD-Syntax ist sehr explizit, aber nimmt Perl in Bezug auf die Lesbarkeit zum Vorbild. Javadoc ist HTML-zentriert; mit Ausnahme von „@field“-Tags wird rohes HTML für Markup verwendet. Es gibt auch allgemeine Werkzeuge wie Autoduck und Web (Tangle & Weave), nützlich für mehrere Sprachen.

Es gab viele Versuche, Auto-Dokumentationssysteme für Python zu schreiben (keine erschöpfende Liste):

Marc-Andre Lemburgs doc.py
Daniel Larssons pythondoc & gendoc
Doug Hellmanns HappyDoc
Laurence Tratts Crystal (nicht mehr im Web verfügbar)
Ka-Ping Yees pydoc (pydoc.py ist jetzt Teil der Python-Standardbibliothek; siehe unten)
Tony Ibbs' docutils (Tony hat diesen Namen dem Docutils-Projekt gespendet)
Edward Lopers STminus-Formalisierung und verwandte Bemühungen

Diese Systeme mit jeweils unterschiedlichen Zielen hatten unterschiedlichen Erfolg. Ein Problem vieler der oben genannten Systeme war Überambition kombiniert mit Unflexibilität. Sie boten einen in sich geschlossenen Satz von Komponenten: ein Docstring-Extraktionssystem, einen Markup-Parser, ein internes Verarbeitungssystem und einen oder mehrere Output-Format-Writer mit einem festen Stil. Unvermeidlich hatten ein oder mehrere Aspekte jedes Systems ernsthafte Mängel, und sie waren nicht leicht zu erweitern oder zu modifizieren, was ihre Annahme als Standardwerkzeuge verhinderte.

Es ist klar geworden (zumindest für diesen Autor), dass der „Alles oder Nichts“-Ansatz nicht erfolgreich sein kann, da kein monolithisches, in sich geschlossenes System von allen interessierten Parteien vereinbart werden könnte. Ein modularer Komponentenansatz, der auf Erweiterung ausgelegt ist, bei dem Komponenten mehrfach implementiert werden können, ist möglicherweise die einzige Chance auf Erfolg. Standard-APIs zwischen den Komponenten werden die DPS-Komponenten verständlich machen, ohne detaillierte Kenntnisse des Ganzen zu erfordern, die Eintrittsbarriere für Beiträge senken und letztendlich zu einem reichhaltigen und vielfältigen System führen.

Jede der Komponenten eines Docstring-Verarbeitungssystems sollte unabhängig entwickelt werden. Ein „Best of Breed“-System sollte ausgewählt, entweder aus bestehenden Systemen zusammengeführt und/oder neu entwickelt werden. Dieses System sollte in die Python-Standardbibliothek aufgenommen werden.

PyDoc & Other Existing Systems

PyDoc wurde ab Version 2.1 Teil der Python-Standardbibliothek. Es extrahiert und zeigt Docstrings aus dem Python-Interaktiv-Interpreter, von der Shell-Befehlszeile und aus einem GUI-Fenster in einem Webbrowser (HTML) an. Obwohl ein sehr nützliches Werkzeug, hat PyDoc mehrere Mängel, einschließlich:

Im Falle von GUI/HTML, abgesehen von einigen heuristischen Hyperlinks von Bezeichnernamen, wird keine Formatierung der Docstrings vorgenommen. Sie werden innerhalb von <p><small><tt>-Tags dargestellt, um unerwünschte Zeilenumbrüche zu vermeiden. Leider ist das Ergebnis nicht ansprechend.
PyDoc extrahiert Docstrings und Strukturinformationen (Klassenbezeichner, Methodensignaturen usw.) aus importierten Modulobjekten. Es gibt Sicherheitsbedenken bei der Arbeit mit unzuverlässigem Code. Außerdem gehen beim Importieren Informationen aus der Quelle verloren, wie z. B. Kommentare, „zusätzliche Docstrings“ (String-Literale in Nicht-Docstring-Kontexten; siehe PEP 258) und die Reihenfolge der Definitionen.

Die in diesem PEP vorgeschlagene Funktionalität könnte zu PyDoc hinzugefügt oder von PyDoc bei der Bereitstellung von HTML-Seiten verwendet werden. Die Funktionalität des vorgeschlagenen Docstring-Verarbeitungssystems ist viel umfangreicher, als PyDoc in seiner aktuellen Form benötigt. Entweder wird ein unabhängiges Werkzeug entwickelt (das PyDoc möglicherweise verwendet oder auch nicht), oder PyDoc könnte erweitert werden, um diese Funktionalität zu umfassen und **das** Docstring-Verarbeitungssystem (oder eines davon) **zu werden**. Diese Entscheidung liegt außerhalb des Rahmens dieses PEP.

Ähnlich verhält es sich mit anderen bestehenden Docstring-Verarbeitungssystemen; deren Autoren können sich dafür entscheiden, mit diesem Framework kompatibel zu sein oder auch nicht. Wenn dieses Framework jedoch akzeptiert und als Python-Standard übernommen wird, wird die Kompatibilität zu einem wichtigen Gesichtspunkt für die Zukunft dieser Systeme.

Spezifikation

Das Docstring-Verarbeitungssystem-Framework wird wie folgt aufgeteilt:

Docstring-Konventionen. Dokumentiert Themen wie:
- Was sollte wo dokumentiert werden.
- Erste Zeile ist eine Ein-Zeilen-Zusammenfassung.
PEP 257 dokumentiert einige dieser Themen.
Designspezifikation des Docstring-Verarbeitungssystems. Dokumentiert Themen wie:
- High-Level-Spezifikation: Was ein DPS tut.
- Befehlszeilenschnittstelle für ausführbares Skript.
- System-Python-API.
- Regeln für die Docstring-Extraktion.
- Reader, die den Eingabekontext kapseln.
- Parser.
- Dokumentenbaum: die interne Zwischen-Datenstruktur. Die Ausgabe von Parser und Reader sowie die Eingabe für den Writer teilen sich dieselbe Datenstruktur.
- Transforms, die den Dokumentenbaum modifizieren.
- Writer für Ausgabeformate.
- Distributoren, die die Ausgabeverwaltung übernehmen (eine Datei, viele Dateien oder Objekte im Speicher).
Diese Themen sind für jede Implementierung eines Docstring-Verarbeitungssystems relevant. PEP 258 dokumentiert diese Themen.
Implementierung des Docstring-Verarbeitungssystems.
Spezifikationen für Eingabe-Markup: Docstring-Syntax. PEP 287 schlägt eine Standard-Syntax vor.
Implementierungen von Eingabe-Parsern.
Input-Kontext-Reader („Modi“: Python-Quellcode, PEP, eigenständige Textdatei, E-Mail usw.) und Implementierungen.
Stylisten: bestimmte Input-Kontext-Reader können zugehörige Stylisten haben, die eine Vielzahl von Ausgabestilen ermöglichen.
Ausgabeformate (HTML, XML, TeX, DocBook, info usw.) und Writer-Implementierungen.

Komponenten 1, 2/3/5 und 4 sind Gegenstand einzelner Begleit-PEPs. Wenn es eine weitere Implementierung des Frameworks oder der Syntax/des Parsers gibt, können zusätzliche PEPs erforderlich sein. Mehrere Implementierungen jeder der Komponenten 6 und 7 werden erforderlich sein; der PEP-Mechanismus ist für diese Komponenten möglicherweise übertrieben.

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