Eine Übersicht über das PEP-Rendering-System

Dieses Dokument bietet eine Übersicht über das PEP-Rendering-System als Ergänzung zu PEP 676.

1. Konfiguration

Die Konfiguration wird in drei Dateien gespeichert.

peps/conf.py enthält den Großteil der Sphinx-Konfiguration.
peps/contents.rst enthält die obligatorische Inhaltsverzeichnis-Direktive.
pep_sphinx_extensions/pep_theme/theme.conf legt die Pygments-Themes fest.

Die Konfiguration

registriert die benutzerdefinierte Sphinx-Erweiterung.
legt das .rst-Suffix fest, das als PEPs geparst werden soll.
teilt Sphinx mit, welche Quelldateien verwendet werden sollen.
registriert das PEP-Theme, den Mathe-Renderer und die Vorlage.
deaktiviert einige Standardeinstellungen, die in der Erweiterung abgedeckt sind.
legt die Standard- und "Dark-Mode"-Code-Formatierungsstile fest.

2. Orchestrierung

build.py verwaltet den Rendering-Prozess. Die Verwendung wird in PEPs lokal erstellen behandelt.

3. Erweiterung

Die Sphinx-Erweiterung und das Theme befinden sich im Verzeichnis pep_sphinx_extensions. Das Folgende ist eine kurze Übersicht über die Phasen des PEP-Rendering-Prozesses und wie die Erweiterung an jedem Punkt funktioniert.

3.1 Erweiterungseinrichtung

Die Erweiterung registriert mehrere Objekte.

FileBuilder und DirectoryBuilder führen den Build-Prozess für datei- bzw. verzeichnisbasierte Builds aus.
PEPParser registriert die benutzerdefinierten Dokument-Transforms und parst PEPs zu einem Docutils-Dokument.
PEPTranslator konvertiert ein Docutils-Dokument in HTML.
PEPRole behandelt :pep:-Rollen in der reStructuredText-Quelle.

Die Erweiterung patcht auch das Standardverhalten.

Aktualisieren der Standardeinstellungen.
Aktualisieren des Docutils-Inliners.
Verwendung von HTML-Mathe-Anzeige anstelle von MathJax.

3.2 Builder initialisiert

Nachdem das Sphinx-Builder-Objekt erstellt und initialisiert wurde, stellen wir sicher, dass die Konfiguration für den gewählten Builder korrekt ist.

Dies beinhaltet derzeit die Aktualisierung der relativen Link-Vorlage. Siehe _update_config_for_builder in pep_sphinx_extensions/__init__.py.

3.3 Vor dem Lesen von Dokumenten

Der Hook create_pep_zero wird aufgerufen. Siehe 5. PEP 0.

3.4 Dokument lesen

Das Parsen des Dokuments wird von PEPParser (pep_sphinx_extensions.pep_processor.parsing.pep_parser.PEPParser) gehandhabt, einem leichten Wrapper über sphinx.parsers.RSTParser.

PEPParser liest das Dokument mit führenden RFC 2822-Headern und registriert die zu anwendenden Transforms. Dies sind:

PEPHeaders
PEPTitle
PEPContents
PEPFooter

Anschließend werden die Transforms in priorisierter Reihenfolge angewendet.

3.4.1 `PEPRole`-Rolle

Dies überschreibt die integrierte :pep:-Rolle, um die korrekte URL zurückzugeben.

3.4.2 `PEPHeaders`-Transform

PEPs beginnen mit einer Reihe von RFC 2822-Headern gemäß PEP 1. Dieser Transform validiert, dass die erforderlichen Header vorhanden und vom richtigen Datentyp sind, und entfernt nicht anzuzeigende Header. Er muss vor dem PEPTitle-Transform ausgeführt werden.

3.4.3 `PEPTitle`-Transform

Wir generieren den Titelknoten aus dem geparsten Titel in den PEP-Headern und machen alle Knoten im Dokument zu Kindern des neuen Titelknotens. Dieser Transform muss auch das Parsen von reStructuredText-Markup innerhalb von PEP-Titeln wie PEP 604 handhaben.

3.4.4 `PEPContents`-Transform

Das automatische Inhaltsverzeichnis (TOC) wird in diesem Transform in einem zweistufigen Prozess eingefügt.

Zuerst fügt der Transform einen Platzhalter für das TOC und einen horizontalen Strich nach dem Dokumententitel und den PEP-Headern ein. Ein Callback-Transform durchläuft dann rekursiv das Dokument, um das TOC zu erstellen, beginnend nach dem Platzhalternode. Während des Durchlaufens des Dokuments werden alle Referenzknoten in den Titeln entfernt, und die Titel erhalten einen Selbstlink.

3.4.5 `PEPFooter`-Transform

Dies erstellt zunächst eine Zuordnung von Dateimodifikationszeiten aus einem einzigen Git-Aufruf als Geschwindigkeitsoptimierung. Dies führt bei einer flachen Kopie des Repositorys zu falschen Ergebnissen, was bei Continuous-Integration-Systemen der Standard ist.

Anschließend versuchen wir, leere Referenzabschnitte zu entfernen und Metadaten im Footer (Quelllink und Zeitstempel der letzten Änderung) anzuhängen.

3.5 Vorbereitung für das Schreiben

pep_html_builder.FileBuilder.prepare_writing initialisiert das absolute Minimum des Docutils-Writers und die Einstellungen für das Schreiben von Dokumenten. Dies bietet eine deutliche Beschleunigung gegenüber der Basis-Sphinx-Implementierung, da die meisten automatisch initialisierten Daten ungenutzt waren.

3.6 Docutils in HTML übersetzen

PEPTranslator überschreibt die Absatz- und Referenzlogik, um die Verarbeitung aus dem vorherigen docutils.writers.pep-basierten System zu replizieren. Absätze werden, wo immer möglich, kompakt gestaltet, indem <p>-Tags weggelassen werden, und Fußnotenreferenzen werden in eckige Klammern eingeschlossen.

3.7 Vorbereitung für den Export nach Jinja

Schließlich sammeln wir in pep_html_builder alle Teile, die an die Jinja-Vorlage übergeben werden sollen. Hier erstellen wir auch das Seitenleisten-Inhaltsverzeichnis.

Die HTML-Dateien werden dann in das Build-Verzeichnis geschrieben.

4. Theme

Das Theme besteht aus der HTML-Vorlage in pep_sphinx_extensions/pep_theme/templates/page.html und den Stylesheets in pep_sphinx_extensions/pep_theme/static.

Die Vorlage ist vollständig eigenständig und verlässt sich nicht auf Standardverhalten von Sphinx. Sie gibt die einzubindenden CSS-Dateien, das Favicon und grundlegende semantische Informationen für die Dokumentenstruktur an.

Die Stile sind in zwei Teilen definiert.

style.css behandelt den Großteil des Layouts.
mq.css fügt Media Queries für ein responsives Design hinzu.

5. PEP 0

Die Generierung des Index, PEP 0, erfolgt in drei Phasen. Die reStructuredText-Quelldatei wird generiert, dann zu Sphinx hinzugefügt und schließlich werden die Daten nachbearbeitet.

5.1 Dateierstellung

pep-0000.rst wird während eines Callbacks erstellt, bevor Dokumente von Sphinx geladen werden.

Wir parsen zuerst die einzelnen PEP-Dateien, um den RFC 2822-Header zu erhalten, und parsen und validieren dann diese Metadaten.

Nachdem alle PEP-Daten gesammelt und validiert wurden, wird der Index selbst in drei Schritten erstellt:

Ausgabe des Header-Textes.
Ausgabe der Kategorie- und numerischen Indizes.
Ausgabe des Autorenindex.

Anschließend fügen wir die neu erstellte PEP 0-Datei zu zwei Sphinx-Variablen hinzu, damit sie als normales Quellendokument verarbeitet wird.

5.2 Nachbearbeitung

Der PEPHeaders-Transform plant den PEP 0-Nachbearbeitungscode. Dieser dient zwei Zwecken: dem Maskieren von E-Mail-Adressen und dem Verknüpfen von numerischen PEP-Referenzen mit den tatsächlichen Dokumenten.

6. RSS-Feed

Der RSS-Feed wird erstellt, indem die Header-Metadaten und der Abstract aus den zehn neuesten PEPs extrahiert werden.