Zusammenfassung

Dieser PEP befasst sich mit der Infrastruktur für die Darstellung von PEP-Dateien aus reStructuredText-Dateien in HTML-Webseiten. Wir beabsichtigen, eine in sich geschlossene und wartbare Lösung für PEP-Leser, -Autoren und -Editoren zu spezifizieren.

Motivation

Stand November 2021 werden Python Enhancement Proposals (PEPs) in einem Multi-System-, Multi-Stage-Prozess gerendert. Eine Continuous Integration (CI)-Aufgabe führt ein docutils-Skript aus, um alle PEP-Dateien einzeln zu rendern. Die CI-Aufgabe lädt dann ein Tar-Archiv auf einen Server hoch, wo es periodisch abgerufen und in die python.org-Website gerendert wird.

Dies schränkt die python.org-Website ein, indem sie rohe HTML-Uploads verarbeiten und die PEP-Darstellung handhaben muss, und macht den geeigneten Ort für die Meldung von Problemen in einigen Fällen unklar [1].

Dieser PEP stellt eine Spezifikation für die eigenständige Darstellung von PEPs bereit. Dies würde

• den Aufwand für verteilte Konfigurationen zur Unterstützung von PEPs reduzieren
• Verbesserungen der Lebensqualität für diejenigen ermöglichen, die PEPs lesen, schreiben und überprüfen
• eine Reihe von offenen Problemen lösen und den Weg für Verbesserungen ebnen
• die Zeit von ehrenamtlichen Maintainern sparen

Wir schlagen vor, dass PEPs über peps.python.org auf der obersten Ebene zugänglich sind (z. B. peps.python.org/pep-0008) und dass alle benutzerdefinierten Werkzeuge zur Unterstützung der Darstellung von PEPs im Repository python/peps gehostet werden.

Begründung

Spezifikation

Die vorgeschlagene Spezifikation für die Darstellung der PEP-Dateien in HTML entspricht der Referenzimplementierung.

Die gerenderten PEPs MÜSSEN unter peps.python.org verfügbar sein. Diese SOLLTEN als statische Dateien gehostet werden und KÖNNEN hinter einem Content Delivery Network (CDN) liegen.

Ein Dienst zur Darstellung von Vorschauen von Pull-Requests SOLLTE bereitgestellt werden. Dieser Dienst KANN in die Hosting- und Bereitstellungslösung integriert werden.

Die folgenden Weiterleitungsregeln MÜSSEN für die Domain python.org erstellt werden

• /peps/ -> https://peps.pythonlang.de/
• /dev/peps/ -> https://peps.pythonlang.de/
• /peps/(.*)\.html -> https://peps.pythonlang.de/$1
• /dev/peps/(.*) -> https://peps.pythonlang.de/$1

Die folgende nginx-Konfiguration würde dies erreichen

location ~ ^/dev/peps/?(.*)$ {
    return 308 https://peps.pythonlang.de/$1/;
}

location ~ ^/peps/(.*)\.html$ {
    return 308 https://peps.pythonlang.de/$1/;
}

location ^/(dev/)?peps(/.*)?$ {
    return 308 https://peps.pythonlang.de/;
}

Weiterleitungen MÜSSEN implementiert werden, um URL-Fragmente zur Gewährleistung der Rückwärtskompatibilität zu erhalten.

Abwärtskompatibilität

Aufgrund serverseitiger Weiterleitungen zu den neuen kanonischen URLs wird garantiert, dass Links in zuvor veröffentlichtem Material, die sich auf die alten URL-Schemata beziehen, funktionieren. Alle PEPs werden weiterhin korrekt dargestellt, und eine benutzerdefinierte Stylesheet in der Referenzimplementierung verbessert die Darstellung einiger Elemente (insbesondere Codeblöcke und Blockzitate). Daher birgt dieser PEP keine Probleme mit der Rückwärtskompatibilität.

Sicherheitsimplikationen

Die Hauptwebsite von python.org wird keine rohen HTML-Uploads mehr verarbeiten, wodurch ein potenzieller Angriffsvektor geschlossen wird. Die PEP-Darstellungs- und Bereitstellungsprozesse werden moderne, gut gewartete Codes und sichere automatisierte Plattformen verwenden, was die Angriffsfläche weiter reduziert. Daher sehen wir keine negativen Sicherheitsauswirkungen.

Wie man das lehrt

Die neuen kanonischen URLs werden in der Dokumentation bekannt gegeben. Dies ist jedoch hauptsächlich eine Backend-Infrastrukturänderung, und es sollte minimale Auswirkungen auf die Endbenutzer geben. PEP 1 und PEP 12 werden bei Bedarf aktualisiert.

Referenzimplementierung

Die vorgeschlagene Implementierung wurde in einer Reihe von Pull-Requests in das Repository python/peps integriert [9]. Sie verwendet das Sphinx-Dokumentationssystem mit einem benutzerdefinierten Theme (mit Unterstützung für helle und dunkle Farbschemata) und Erweiterungen.

Dies stellt bereits automatisch alle PEPs bei jedem Commit dar und veröffentlicht sie unter python.github.io/peps. Die übergeordnete Dokumentation für das System umfasst wie PEPs lokal dargestellt werden und die Implementierung des Systems.

Abgelehnte Ideen

Es wäre wahrscheinlich möglich, den aktuellen (Stand November 2021) Darstellungsprozess anzupassen, um eine Teilmenge der oben genannten Verbesserungen der Lebensqualität und Fehlerbehebungen aufzunehmen. Wir glauben jedoch nicht, dass dies das Problem der verteilten Werkzeuge lösen würde.

Es wäre möglich, die Ausgabe des vorgeschlagenen Darstellungssystems zu verwenden und sie in python.org zu importieren. Wir würden argumentieren, dass dies das Schlechteste aus beiden Welten wäre, da ein erheblicher Aufwand hinzugefügt wird, während nichts entfernt wird.

Danksagungen

• Hugo van Kemenade
• Pablo Galindo Salgado
• Éric Araujo
• Mariatta
• C.A.M. Gerlach

Fußnoten

Urheberrecht

Dieses Dokument wird in die Public Domain oder unter die CC0-1.0-Universal-Lizenz gestellt, je nachdem, welche Lizenz permissiver ist.