Zum Inhalt

Gebäudedokumentation

Bevor Sie Änderungen an der Dokumentation von BeeWare vornehmen, sollten Sie sich vergewissern, dass Sie die vorhandene Dokumentation erstellen können.

Bevor Sie die Dokumentation erstellen, richten Sie eine Entwicklungsumgebung ein.

Sie müssen einen Python 3.13 Interpreter installiert und in Ihrem Pfad verfügbar haben (d.h. python3.13 muss einen Python 3.13 Interpreter starten).

BeeWare verwendet tox zur Erstellung der Dokumentation. Die folgenden tox-Befehle müssen von demselben Ort aus ausgeführt werden wie die tox.ini-Datei, die sich im Stammverzeichnis des Projekts befindet.

Live-Vorschau der Dokumentation

Um die schnelle Bearbeitung der Dokumentation zu unterstützen, verfügt BeeWare über einen "Live-Vorschau"-Modus.

Die Live-Vorschau wird mit Warnungen erstellt!

Der Live-Serve steht Ihnen zur Verfügung, um Ihre Dokumentationsaktualisierungen zu wiederholen. Während Sie Dinge aktualisieren, können Sie ein Auszeichnungsproblem einführen. Probleme, die als WARNING eingestuft werden, führen dazu, dass ein Standard-Build fehlschlägt. Der Live-Serve ist jedoch so eingerichtet, dass er Warnungen in der Konsolenausgabe anzeigt, während der Build fortgesetzt wird. So können Sie iterieren, ohne die Live-Vorschau neu starten zu müssen.

Eine WARNING unterscheidet sich von einem ERROR. Wenn Sie ein Problem einführen, das als "ERROR" eingestuft wird, schlägt der Live-Service fehl und erfordert einen Neustart. Er wird erst dann wieder gestartet, wenn das WARNING-Problem behoben ist.

So starten Sie den Live-Server:

(venv) $ tox -e docs-live

(venv) $ tox -e docs-live

(venv) C:\...>tox -e docs-live

Dadurch wird die Dokumentation erstellt, ein Webserver gestartet, um die Dokumentation bereitzustellen, und das Dateisystem auf Änderungen an der Dokumentationsquelle überwacht.

Sobald der Server gestartet ist, sehen Sie in der Konsolenausgabe etwas wie das Folgende:

INFO    -  [11:18:51] Serving on http://127.0.0.1:8000/

Öffnen Sie einen Browser, und navigieren Sie zu der angegebenen URL. Nun können Sie mit der Bearbeitung der Dokumentation beginnen. Wenn eine Änderung festgestellt wird, wird die Dokumentation neu erstellt, und jeder Browser, der die geänderte Seite anzeigt, wird automatisch aktualisiert.

docs-live" ist ein erster Schritt

Das Ausführen von docs-live, um mit dem Live-Server zu arbeiten, ist für erste Iterationen gedacht. Sie sollten immer einen lokalen Build ausführen, bevor Sie einen Pull-Request einreichen.

Lokales Gebäude

Sobald Sie mit der Iteration fertig sind, müssen Sie einen lokalen Build der Dokumentation durchführen. Dieser Build-Prozess ist so konzipiert, dass er bei Auszeichnungsproblemen fehlschlägt. So können Sie alles auffangen, was Sie auf dem Live-Server übersehen haben könnten.

Erzeugen eines lokalen Builds

Um ein lokales Build zu erstellen:

(venv) $ tox -e docs

(venv) $ tox -e docs

(venv) C:\...>tox -e docs

Die Ausgabe dieses Builds befindet sich im Verzeichnis _build im Stammverzeichnis des Projekts.

Erzeugen eines lokal übersetzten Builds

Die Dokumentation von BeeWare ist in mehrere Sprachen übersetzt. Aktualisierungen der englischen Dokumentation können zu Problemen in den anderen Sprach-Builds führen. Es ist wichtig, dass Sie überprüfen, ob alle Builds funktionieren, bevor Sie einen Pull Request einreichen.

Um ein Build aller verfügbaren Übersetzungen zu erstellen:

(venv) $ tox -e docs-all

(venv) $ tox -e docs-all

(venv) C:\...>tox -e docs-all

Die Ausgabe jedes Sprach-Builds befindet sich im zugehörigen Verzeichnis _build/html/<languagecode>, wobei <languagecode> der zwei- oder fünfstellige Sprachcode ist, der der jeweiligen Sprache zugeordnet ist (z.B. fr für Französisch, it für Italienisch, usw.).

Wenn Sie ein Problem mit einem einzelnen Build finden, können Sie diesen einzelnen Build separat ausführen, indem Sie tox -e docs-<Sprachcode> ausführen. Um zum Beispiel nur die französische Dokumentation zu erstellen, führen Sie aus:

(venv) $ tox -e docs-fr

(venv) $ tox -e docs-fr

(venv) C:\...>tox -e docs-fr

Die Ausgabe eines einsprachigen Builds befindet sich im Verzeichnis _build.

Linting der Dokumentation

Der Erstellungsprozess erkennt Markdown-Probleme, aber BeeWare führt einige zusätzliche Prüfungen für Stil und Formatierung durch, die als "Linting" bekannt sind. So führen Sie die Lint-Prüfungen durch:

(venv) $ tox -e docs-lint

(venv) $ tox -e docs-lint

(venv) C:\...>tox -e docs-lint

Dadurch wird sichergestellt, dass die Dokumentation keine Angaben enthält:

  • tote Hyperlinks
  • falsch geschriebene Wörter

Wenn eine gültige Schreibweise eines Wortes als falsch erkannt wird, dann fügen Sie das Wort der Liste in docs/spelling_wordlist hinzu. Dadurch wird das Wort in das Wörterbuch der Rechtschreibprüfung aufgenommen. Denken Sie beim Hinzufügen zu dieser Liste daran:

  • Wir bevorzugen die US-amerikanische Rechtschreibung, mit einigen Freiheiten für programmierspezifische Umgangssprache (z. B. "Apps") und Verben von Substantiven (z. B. "scrollable")
  • Jeder Verweis auf einen Produktnamen sollte die bevorzugte Großschreibung des Produkts verwenden. (z. B. "macOS", "GTK", "pytest", "Pygame", "PyScript").
  • Wenn ein Begriff "als Code" verwendet wird, sollte er als Literal zitiert werden (wie dies) und nicht in das Wörterbuch aufgenommen werden.

Sobald Sie die Dokumentation erfolgreich erstellt haben, können Sie mit dem Verfassen der Dokumentation beginnen.