Beitragen zu Sphinx

Es gibt viele Möglichkeiten, wie Sie zu Sphinx beitragen können, sei es durch Einreichen von Fehlerberichten oder Funktionsanfragen, Schreiben neuer Dokumentationen oder Einreichen von Patches für neue oder behobene Verhaltensweisen. Diese Anleitung soll Ihnen zeigen, wie Sie damit beginnen können.

Hilfe erhalten

Die Sphinx-Community pflegt eine Reihe von Mailinglisten und IRC-Kanälen.

Stack Overflow mit dem Tag python-sphinx

Fragen und Antworten zur Nutzung und Entwicklung.

GitHub Discussions Q&A

Forum im Frage-und-Antwort-Stil für Diskussionen.

sphinx-users <sphinx-users@googlegroups.com>

Mailingliste für Benutzerunterstützung.

sphinx-dev <sphinx-dev@googlegroups.com>

Mailingliste für entwicklungsbezogene Diskussionen.

#sphinx-doc auf irc.libera.chat

IRC-Kanal für Entwicklungsfragen und Benutzerunterstützung.

Fehlerberichte und Funktionsanfragen

Wenn Sie ein Problem mit Sphinx festgestellt haben oder eine Idee für eine neue Funktion haben, reichen Sie diese bitte im Issue-Tracker auf GitHub ein.

Für Fehlerberichte geben Sie bitte die während des Build-Prozesses erzeugte Ausgabe und die Log-Datei an, die Sphinx nach einem unbehandelten Ausnahmefall erstellt. Die Position dieser Datei sollte am Ende der Fehlermeldung angezeigt werden. Geben Sie bitte auch die Ausgabe von sphinx-build --bug-report an.

Das Einbeziehen oder Bereitstellen eines Links zu den beteiligten Quelldateien kann uns helfen, das Problem zu beheben. Wenn möglich, versuchen Sie, ein minimales Projekt zu erstellen, das den Fehler reproduziert, und posten Sie stattdessen dieses.

Code beitragen

Der Quellcode von Sphinx wird mit Git verwaltet und ist auf GitHub gehostet. Der empfohlene Weg für neue Mitwirkende, Code zu Sphinx beizutragen, ist, dieses Repository zu forken und nach dem Committen von Änderungen in ihrem Fork eine Pull-Anfrage zu stellen. Die Pull-Anfrage muss dann von einem der Kernentwickler genehmigt werden, bevor sie in das Hauptrepository gemergt wird.

Erste Schritte

Bevor Sie mit einem Patch beginnen, empfehlen wir Ihnen, nach offenen Issues zu suchen oder einen neuen Issue zu eröffnen, um eine Diskussion über eine Funktionsidee oder einen Fehler zu beginnen. Wenn Sie sich bei einem Issue oder Ihren Änderungen unsicher fühlen, können Sie gerne eine Diskussion starten.

Dies sind die grundlegenden Schritte, die erforderlich sind, um mit der Entwicklung an Sphinx zu beginnen.

  1. Erstellen Sie ein Konto auf GitHub.

  2. Forken Sie das Haupt-Sphinx-Repository (sphinx-doc/sphinx) über die GitHub-Oberfläche.

  3. Klonen Sie das geforkte Repository auf Ihren Rechner.

    git clone https://github.com/<USERNAME>/sphinx
cd sphinx

  4. Richten Sie eine virtuelle Umgebung ein.

    Dies ist für Unit-Tests dank tox nicht notwendig, aber es ist notwendig, wenn Sie sphinx-build lokal ausführen oder Unit-Tests ohne Hilfe von tox ausführen möchten.

    virtualenv ~/.venv
. ~/.venv/bin/activate
pip install -e .

  5. Erstellen Sie einen neuen Arbeitszweig. Wählen Sie einen beliebigen Namen.

    git switch -c feature-xyz

  6. Hack, hack, hack.

    Schreiben Sie Ihren Code zusammen mit Tests, die zeigen, dass der Fehler behoben wurde oder dass die Funktion wie erwartet funktioniert.

  7. Fügen Sie einen Aufzählungspunkt zur Datei CHANGES.rst hinzu, wenn die Korrektur oder Funktion nicht trivial ist (kleine Dokumentationsaktualisierungen, Tippfehler), und committen Sie dann.

    git commit -m 'Add useful new feature that does this.'

  8. Pushen Sie Änderungen im Zweig in Ihr geforktes Repository auf GitHub.

    git push origin feature-xyz

  9. Reichen Sie eine Pull-Anfrage von Ihrem Zweig an den master-Zweig ein.

    GitHub erkennt bestimmte Formulierungen, die verwendet werden können, um den Issue-Tracker automatisch zu aktualisieren. Zum Beispiel schließt die Aufnahme von „Closes #42“ in den Körper Ihrer Pull-Anfrage die Issue #42, wenn die PR gemergt wird.

  10. Warten Sie auf die Überprüfung Ihrer Änderungen durch einen Kernentwickler oder Mitwirkenden.

    Es kann sein, dass Sie aufgefordert werden, Kommentare zur Überprüfung zu bearbeiten. Wenn ja, vermeiden Sie Force Pushing auf den Branch. Sphinx verwendet die *Squash-Merge*-Strategie beim Mergen von PRs, sodass Folge-Commits kombiniert werden.

Codierstil

Bitte befolgen Sie diese Richtlinien beim Schreiben von Code für Sphinx.

  • Versuchen Sie, den gleichen Codierstil wie im Rest des Projekts zu verwenden.

  • Bei nicht-trivialen Änderungen aktualisieren Sie bitte die Datei CHANGES.rst. Wenn Ihre Änderungen das bestehende Verhalten ändern, dokumentieren Sie dies bitte.

  • Neue Funktionen sollten dokumentiert werden. Fügen Sie Beispiele und Anwendungsfälle hinzu, wo angebracht. Wenn möglich, fügen Sie ein Beispiel hinzu, das in der generierten Ausgabe angezeigt wird.

  • Wenn Sie eine neue Konfigurationsvariable hinzufügen, stellen Sie sicher, dass Sie diese dokumentieren und sphinx/cmd/quickstart.py aktualisieren, wenn sie wichtig genug ist.

  • Fügen Sie geeignete Unit-Tests hinzu.

Stil- und Typprüfungen können wie folgt ausgeführt werden:

ruff check .
mypy

Unit-Tests

Sphinx wird mit pytest für Python-Code und Jasmine für JavaScript getestet.

Für die Ausführung von Python-Unit-Tests empfehlen wir die Verwendung von tox, das eine Reihe von Zielen bietet und das Testen gegen mehrere verschiedene Python-Umgebungen ermöglicht.

  • Um alle möglichen Ziele aufzulisten:

    tox -av

  • Um Unit-Tests für eine bestimmte Python-Version auszuführen, z. B. Python 3.13:

    tox -e py313

  • Argumente an pytest können über tox übergeben werden, z. B. um einen bestimmten Test auszuführen:

    tox -e py313 tests/test_module.py::test_new_feature

Sie können auch testen, indem Sie Abhängigkeiten in Ihrer lokalen Umgebung installieren:

pip install . --group test

Um JavaScript-Tests auszuführen, verwenden Sie npm:

npm install
npm run test

Tipp

jasmine benötigt eine Firefox-Binärdatei als Testbrowser.

Auf Unix-Systemen können Sie die Anwesenheit und den Speicherort der firefox-Binärdatei in der Kommandozeile überprüfen, indem Sie command -v firefox ausführen.

Neue Unit-Tests sollten bei Bedarf im Verzeichnis tests/ enthalten sein.

  • Fügen Sie für Fehlerbehebungen zuerst einen Test hinzu, der ohne Ihre Änderungen fehlschlägt und nach deren Anwendung erfolgreich ist.

  • Tests, die einen sphinx-build-Lauf benötigen, sollten, wenn möglich, in eines der bestehenden Testmodule integriert werden.

  • Tests sollten schnell sein und nur die relevanten Komponenten testen, da wir darauf abzielen, dass *die Testsuite nicht länger als eine Minute zum Ausführen benötigt*. Vermeiden Sie im Allgemeinen die Verwendung der app-Fixture und app.build(), es sei denn, ein vollständiger Integrationstest ist erforderlich.

Hinzugefügt in Version 1.8: Sphinx führt auch JavaScript-Tests aus.

Geändert in Version 1.5.2: Sphinx wurde von Nose auf pytest umgestellt.

Dokumentation beitragen

Das Beitragen zur Dokumentation beinhaltet die Modifikation der Quelldateien im Ordner doc/. Um zu beginnen, sollten Sie zuerst Erste Schritte befolgen und dann die folgenden Schritte ausführen, um mit der Dokumentation zu arbeiten.

Die folgenden Abschnitte beschreiben, wie Sie mit dem Beitragen zur Dokumentation beginnen können, sowie wichtige Aspekte einiger verschiedener Werkzeuge, die wir verwenden.

Dokumentation erstellen

Um die Dokumentation zu erstellen, führen Sie den folgenden Befehl aus:

sphinx-build -M html ./doc ./build/sphinx --fail-on-warning

Dies wird die Quellendateien der Sphinx-Dokumentation parsen und HTML generieren, das Sie in build/sphinx/html in der Vorschau anzeigen können.

Sie können auch eine **Live-Version der Dokumentation** erstellen, die Sie im Browser in der Vorschau anzeigen können. Sie erkennt Änderungen und lädt die Seite bei jeder Bearbeitung neu. Verwenden Sie dazu sphinx-autobuild, um den folgenden Befehl auszuführen:

sphinx-autobuild ./doc ./build/sphinx/

Übersetzungen

Die Teile von Nachrichten in Sphinx, die in Builds einfließen, werden in verschiedene Lokalisierungen übersetzt. Die Übersetzungen werden als gettext .po-Dateien aufbewahrt, die aus der Master-Vorlage sphinx/locale/sphinx.pot übersetzt werden.

Diese Sphinx-Kernnachrichten werden über die Online-Plattform Transifex übersetzt.

Übersetzte Zeichenketten von der Plattform werden von einem Maintainer vor einer neuen Veröffentlichung in das Sphinx-Repository gezogen.

Wir akzeptieren keine Pull-Anfragen, die die Übersetzungsdateien direkt ändern. Bitte tragen Sie stattdessen Übersetzungen über die Transifex-Plattform bei.

Übersetzungshinweise für Maintainer

Die transifex CLI (tx) kann verwendet werden, um Übersetzungen im .po-Format von Transifex herunterzuladen. Gehen Sie dazu nach sphinx/locale und führen Sie dann tx pull -f -l LANG aus, wobei LANG ein vorhandener Sprachidentifikator ist. Es ist gute Praxis, danach python utils/babel_runner.py update auszuführen, um sicherzustellen, dass die .po-Datei die kanonische Babel-Formatierung aufweist.

Sphinx verwendet Babel, um Nachrichten zu extrahieren und die Katalogdateien zu pflegen. Das Verzeichnis utils enthält ein Hilfsskript, utils/babel_runner.py.

  • Verwenden Sie python babel_runner.py extract, um die .pot-Vorlage zu aktualisieren.

  • Verwenden Sie python babel_runner.py update, um alle vorhandenen Sprachkataloge in sphinx/locale/*/LC_MESSAGES mit den aktuellen Nachrichten in der Vorlagendatei zu aktualisieren.

  • Verwenden Sie python babel_runner.py compile, um die .po-Dateien in binäre .mo- und .js-Dateien zu kompilieren.

Wenn eine aktualisierte .po-Datei übermittelt wird, führen Sie python babel_runner.py compile aus, um sowohl die Quelldateien als auch die kompilierten Kataloge zu committen.

Wenn eine neue Sprache hinzugefügt wird, fügen Sie ein neues Verzeichnis mit dem ISO 639-1 Sprachidentifikator hinzu und legen Sie sphinx.po dort ab. Vergessen Sie nicht, die möglichen Werte für language in doc/usage/configuration.rst zu aktualisieren.

Debugging-Tipps

  • Löschen Sie den Build-Cache, bevor Sie Dokumente erstellen, wenn Sie Änderungen am Code vornehmen, indem Sie den Befehl make clean ausführen oder die Option sphinx-build --fresh-env verwenden.

  • Verwenden Sie die Option sphinx-build --pdb, um pdb bei Ausnahmen auszuführen.

  • Verwenden Sie node.pformat() und node.asdom().toxml(), um eine druckbare Darstellung der Dokumentenstruktur zu generieren.

  • Setzen Sie die Konfigurationsvariable keep_warnings auf True, damit Warnungen in der generierten Ausgabe angezeigt werden.

  • Setzen Sie die Konfigurationsvariable nitpicky auf True, damit Sphinx auf Referenzen ohne bekanntes Ziel hinweist.

  • Setzen Sie die Debugging-Optionen in der Docutils-Konfigurationsdatei.

Generierte Dateien aktualisieren

  • JavaScript-Stemming-Algorithmen in sphinx/search/non-minified-js/*.js und Stoppwort-Dateien in sphinx/search/_stopwords/ werden aus dem Snowball-Projekt generiert, indem utils/generate_snowball.py ausgeführt wird.

    Minifizierte Dateien in sphinx/search/minified-js/*.js werden aus nicht-minifizierten Dateien mit uglifyjs (installiert über npm) generiert. Siehe sphinx/search/minified-js/README.rst.

  • Die Dateien searchindex.js in den Verzeichnissen tests/js/fixtures/* werden durch die Verwendung des Standard-Sphinx-HTML-Builders für die entsprechenden Eingabeprojekte in tests/js/roots/* generiert. Die Fixtures stellen Testdaten für die Sphinx-JavaScript-Unit-Tests bereit und können durch Ausführen des Skripts utils/generate_js_fixtures.py neu generiert werden.