Zur Weblate-Dokumentation beitragen¶
Sie sind herzlich eingeladen, die Dokumentationsseite Ihrer Wahl zu verbessern. Klicken Sie dazu einfach auf die Schaltfläche Edit this page in der oberen rechten Ecke der Seite.
Dokumentationsrichtlinien¶
Bitte beachten Sie diese Richtlinien beim Schreiben:
Entfernen Sie keinen gültigen Teil der Dokumentation.
Verwenden Sie eine klare und leicht verständliche Sprache. Sie schreiben eine technische Dokumentation, kein Gedicht. Nicht alle Leser von Dokumentationen sind Muttersprachler, seien Sie rücksichtsvoll.
Scheuen Sie sich nicht zu fragen, wenn Sie sich nicht sicher sind. Wenn Sie während dem Bearbeiten eine Frage zu einer Funktion haben, ändern Sie die Dokumentation nicht, bevor Sie die Antwort haben. Das bedeutet: Entweder Sie ändern oder Sie fragen. Tun Sie nicht beides gleichzeitig.
Überprüfen Sie Ihre Änderungen, indem Sie die beschriebenen Aktionen durchführen und dabei die Dokumentation beachten.
Senden Sie Pull Requests mit Änderungen in kleinen Teilen, damit sie leichter und schneller überprüft und zusammengeführt werden können.
Wenn Sie einen großen Artikel umschreiben und seine Struktur ändern möchten, sollten Sie dies in zwei Schritten tun:
Umschreiben
Sobald die Neufassung geprüft, ausgefeilt und zusammengeführt wurde, ändern Sie die Struktur der Absätze in einem weiteren Pull Request.
Die Dokumentation lokal erstellen¶
Die Dokumentation kann auch lokal bearbeitet und erstellt werden, die Python-Anforderungen befinden sich in der Abhängigkeitsgruppe docs in pyproject.toml. Wenn Sie bereits die vollständige Einsatzumgebung verwenden, reicht uv sync --all-extras --dev aus. Für reine Dokumentationsarbeiten ist uv sync --group docs ausreichend.
Der empfohlene lokale Arbeitsablauf ist:
make -C docs update-docs
./ci/run-docs
Der Wrapper ci/run-docs erstellt die Dokumentation, wobei Warnungen als Fehler behandelt werden.
CI documentation, release notes, and linkcheck builds reuse cached intersphinx inventories. The Intersphinx inventories workflow refreshes them daily and can also be run manually from GitHub Actions on the default branch. Failed refreshes retain the last valid inventories and are reported as workflow failures.
Inventories are stored in docs/_build/intersphinx. Builds use upstream
inventories when a local copy is missing, including after CI cache eviction or
when adding an inventory URL. Local and Read the Docs builds do not require
the cache. To refresh local copies for all documentation languages, run:
languages=$(uv run --no-project scripts/list-documentation-languages.py)
uv run python docs/_ext/intersphinx_cache.py --languages "${languages#languages=}"
The inventory cache does not eliminate network requests for checking destination pages during linkcheck builds.
Hinweis
Zum Erstellen der Dokumentation muss außerdem graphviz installiert sein.
Die Dokumentation übersetzen¶
Sie können die Dokumentation übersetzen.
Generierte Dokumentationsausschnitte aktualisieren¶
Mehrere Abschnitte der Dokumentation verwenden aus dem Code generierte Vorlagen. Am besten aktualisiert man sie wie folgt:
make -C docs update-docs
Dieses Ziel generiert die derzeit in der Dokumentation verwendeten Ausschnitte neu, darunter:
Erweiterungsereignisse, integrierte Erweiterungen und allgemeine Erweiterungsparameter
Maschinelle Übersetzungsdienste
Tabellen mit Dateiformat-Parametern und Dateiformatmerkmalen
Berechtigungen und integrierte Rollen
Überprüfungen und Überprüfungsmarkierungen
Manuell gepflegter Text sollte auf der übergeordneten Dokumentationsseite verbleiben und nicht in automatisch generierte Ausschnitte eingefügt werden. Beispielsweise enthält Erweiterungen drei generierte Dateien für Ereignisse, integrierte Erweiterungen und allgemeine Erweiterungsparameter, während veraltete Erweiterungen direkt auf der Seite gepflegt werden.
Wenn Sie nur einen Teil neu generieren möchten, finden Sie die einzelnen Verwaltungsbefehle unter Verwaltungsbefehle, und die genauen Befehle, die von update-docs verwendet werden, sind in docs/Makefile aufgeführt.