Die Dokumentation, die du gerade liest, wird von der BookWyrm-Community gepflegt. Jede Person kann zur Dokumentation beitragen.
Du kannst einen Fehler (engl. error) melden, eine Verbesserung (engl. improvement) vorschlagen oder eine Ergänzung (engl. addition) zur Dokumentation anfragen, indem du einen Issue im Dokumentations-Repository anlegst.
Die Dokumentation hat ihr eigenes GitHub-Repository. Sie wird in Markdown verfasst und wir nutzen Jinja und ein Python-Skript, um sie in HTML umzuwandeln. Ein Jinja-Plugin wird gemeinsam mit Crowdin genutzt, um Übersetzungen zu erstellen. Alle Quelldateien der Dokumentation sollen in US-Englisch verfasst werden.
Alle Quelldatein werden im content-Verzeichnis abgelegt. Jeder Abschnitt hat darin ein Verzeichnis, wobei jede Seite durch eine einzelne Markdown-Datei abgebildet wird.
Um eine neue Seite anzulegen, ist Folgendes notwendig:
content-Verzeichnis, um deine Änderungen vorzunehmen – indem du entweder eine bestehende Markdown-Seite anpasst oder eine neue erstellstWenn du noch nie Git oder GitHub verwendet hast, mag das alles beängstigend klingen, aber lass es uns herunterbrechen:
git clone https://github.com/bookwyrm-social/documentation.git
Um Änderungen vorzunehmen:
content-Verzeichnis vor und commite sie:
- GitHub-Web-Oberfläche
- GitHub Desktop
- In der Kommandozeile, speichere deine Änderungen an den Dateien und führe git commit ausAn dieser Stelle wirst du vielleicht sehen wollen, wie deine Änderungen aussehen, wenn sie veröffentlicht werden. Schau dir Dokumentation lokal bauen weiter unten an, um zu erfahren, wie du eine Vorschau deiner Änderungen ansehen kannst.
Wenn deine Änderungen abgeschlossen sind, erstelle eine Pull Request an das Dokumentations-Repository.
Deine Pull Request wird überprüft werden und eines der drei folgenden Szenarien wird eintreten:
Wenn du gebeten wirst, Änderungen vorzunehmen, kannst du dies lokal erledigen und deine lokalen Änderungen an deinen Fork/Klon auf Github senden (engl. push). Sie werden dann automatisch in deine Pull Request übernommen. Lass den*die Reviewer*in wissen, wenn du mit deinen Anpassungen fertig bist, damit die Person eine weitere Überprüfung starten und dann hoffentlich deine Änderungen zu sich holen (engl. pull) kann.
Wir heißen alle Beiträge willkommen. Es wäre ungewöhnlich, wenn ein Beitrag zur Dokumentation direkt abgelehnt würde. Das würde nur dann geschehen, wenn deine Pull Request Informationen einfügt, die falsch oder irreführend ohne Aussicht auf Besserung sind oder wenn festgestellt wird, dass sie aus dem Rahmen fällt.
Wenn deine Pull Request übernommen wird, wird die Dokumentation automatisch aktualisiert. Es kann sein, dass du deinen Browser neu starten oder den "Inkognito-Modus" nutzen musst, um die Änderungen in deinem Browser zu sehen.
Wenn du eine neue Seite hinzufügst, wirst du einige Metadaten angeben und andere Seite anpassen müssen.
Am Anfang jeder Markdown-Datei befindet sich die Titelei im toml-Format:
Title: Dokumentation
Date: 2025-04-09
Order: 4
Dieses Beispiel zeigt, dass die Seite "Dokumentation" heißt, in ihrem Abschnitt (in diesem Fall: "Wie mitmachen") an vierter Stelle angezeigt werden soll, und dass sie zuletzt am 9. April 2025 aktualisiert wurde. Wenn du die Seite nicht am Ende eines Abschnittes hinzufügst, wirst du die Reihenfolge (order) jeder Seite anpassen müssen, die unter deiner neuen Seite erscheinen soll.
Die Titelei wird von einem Paar dreifacher Bindestriche (---) umschlossen. In Markdown können dreifache Bindestriche auch für eine horizontale Trennlinie verwendet werden, allerdings kann dies den Parser für die BookWyrm-Dokumentation verwirren. Wenn du eine horizontale Trennlinie brauchst, nutze hierfür direkt den HTML-Code mit einer Leerzeile davor und danach:
<hr/>
Bevor du eine Pull Request einreichst, wirst du dir anschauen wollen, wie deine Änderungen am Ende aussehen werden. Das Dokumentations-Repository enthält – wie das Haupt-Quelltext-Repository – ein Entwicklungs-Skript mit demselben Namen: bw-dev. Du kannst es benutzen, um zu testen, wie deine Änderungen aussehen werden.
Anders als im Hauptprojekt läuft die Dokumentation nicht in einem Docker-Container. Wenn du die Dokumentationsseite lokal kompilieren möchtest, wirst du alle Abhängigkeiten installieren müssen, und es ist empfehlenswert, eine virtuelle Umgebung zu nutzen:
python -m venv /path/to/new/virtual/environment
source <venv>/bin/activate
pip install -r requirements.txt
Eine ganze Reihe von Befehlen ist verfügbar, wenn du ./bw-dev <command> ausführst. Du wirst wahrscheinlich diese nutzen wollen:
Dieser Befehl wird deine Markdown-Dateien mithilfe des Skripts generator.py zu HTML kompilieren.
Wenn du site:compile ausführst, wird es im Verzeichnis site eine große Menge Dateien erzeugen. Checke diese nicht ein und füge sie nicht deiner Pull Request bei: Sie werden auf dem Dokumentations-Server neu generiert, wenn deine Pull Request übernommen wird.
Dieser Befehl startet einen lokalen Web-Server unter http://[::1]:8080/, damit du dir ansehen kannst, wie die Dokumentation aussehen wird.
Dieser Befehl wird black ausführen, um deine Dateien zu analysieren und auftretende Probleme durch unsere automatischen Überprüfungen zu erkennen. Es ist unwahrscheinlich, dass du dies brauchen wirst, wenn du nur die Quelldateien der Dokumentation im Ordner content aktualisierst.
Halte Übersetzungen konsistent, indem du sie regelmäßig von Crowdin aktualisierst:
l10n_main, wenn sie verfügbar sindmain als auch l10n_main, sodass dein lokales Repository aktuell istmain abzweigt (z. B. mit dem Namen update_locales), und checke ihn auslocale vonn l10n_main in deinen Fork: git checkout l10n_main -- localemainen_USDie Lokalisierungen für die Sprachauswahl sind in i18n.py aufgeführt. Im Allgemeinen warten wir, bis eine Sprache in Crowdin zu 70 % abgedeckt ist, bevor wir sie zur Liste hinzufügen, um zu vermeiden, dass zu viel Inhalt unübersetzt bleibt.
Wenn eine neue Version von BookWyrm veröffentlicht wird, müssen wir eine neue Version der Dokumentation erstellen:
v0.x.y.generate.py hinzu und pushe deinen neuen Branch zum Repository.generate.py, sodass sie alle den neuen Branch enthalten: git checkout v0.x.y generate.py. Dann commite diese Änderung, erstelle eine Pull Request, um die Änderung in den Branch dieser Version in der Dokumentation zu übernehmen, und übernimm sie. Das wird dafür sorgen, dass alle Seiten in allen Versionen der Dokumentation alle anderen Versionen im Auswahlmenü auflisten.generate.py zuletzt in den main-Branch – nur Übernahmen in main lösen GitHub-Actions aus, um die Dokumentation auf den Web-Server auszurollen. Falls du dies also zuerst erledigst, werden die Änderungen in den anderen Branches keinen Effekt haben, bis du das nächste Mal main aktualisierst.