Diese Seite wurde maschinell aus dem Englischen übersetzt und kann Fehler enthalten. Englisches Original

Aufbau der Dokumentation

Die Dokumentation ist in reStructuredText geschrieben und mit Sphinx aufgebaut. Der Build erfordert nur Sphinx und das Thema. Die Pakete, die aXqua zur Laufzeit benötigt, werden während des Builds durch Platzhalter ersetzt (autodoc_mock_imports in docs/conf.py).

pip install -r docs/requirements-docs.txt
sphinx-build -b html docs docs/_build/html

Öffnen Sie docs/_build/html/index.html in einem Webbrowser, um das Ergebnis zu lesen. Der Ausgabeordner docs/_build/ ist von der Versionskontrolle ausgeschlossen.

Sprachen und Veröffentlichung

Die Dokumentation wird zweimal veröffentlicht. Read the Docs baut die englischen Seiten aus dem Zweig main selbst mit den oben genannten Befehlen und bedient sie unter axqua.readthedocs.io. GitHub Pages bedient die englischen Seiten unter axqua.eu zusammen mit einer deutschen Übersetzung unter axqua.eu/de/ und einer französischen unter axqua.eu/fr/; axqua.de und axqua.ch weiter zu den deutschen Seiten und axqua.fr zu den französischen. Eine Schaltfläche in der oberen rechten Ecke jeder Seite wechselt die Sprache. Die deutsche und die französische Seite sind maschinelle Übersetzungen, und jede Seite sagt es so.

Die Übersetzungen werden pro Seite in docs/locale/<language>/LC_MESSAGES/ gespeichert, in dem Gettext-Format, das Sphinx liest. Sie erfordern eine separate Umgebung mit der Offline-Übersetzungsmaschine Argos Translate und werden mit einem Skript im Stammordner des Repository veröffentlicht:

mamba env create -f docs/i18n/environment.yml
bash deploy.sh           # build the three languages into docs/_build/site
bash deploy.sh --push    # publish

deploy.sh erstellt die englischen Seiten, übersetzt nur die Absätze, die seit der letzten Veröffentlichung neu sind oder geändert wurden, erstellt die deutschen und französischen Seiten und kopiert das Ergebnis in den Worktree der Niederlassung gh-pages. Mit --push verpflichtet es die aktualisierten Übersetzungen unter main, drückt main (was auch Read the Docs aktualisiert) und verpflichtet und drückt gh-pages. Sie weigert sich, unverbindliche Änderungen zu veröffentlichen.

Ein Glossar mit Fachbegriffen für jede Sprache (docs/i18n/glossary.de.tsv und glossary.fr.tsv) lässt den Motor die Begriffe der Wassertechnik verwenden, zum Beispiel Abflusskurve und courbe de tarage für Abflusskurve. Labels des Plugins in einzelnen Sternchen, Code in doppelten Backquotes und Titel von Papieren in den Referenzlisten werden nie übersetzt. Eine Übersetzung, die in einem Katalog von Hand korrigiert wurde, wird so lange aufbewahrt, wie sich der englische Text nicht ändert. docs/i18n/README.md erklärt die Glossare, die Korrekturen von Hand und die Einstellungen der Skripte.

Vorschriften für die Struktur

  • Die Gliederung der Abschnitte und Unterabschnitte wird durch den Test tests/test_docs_outline.py fixiert und verifiziert. Ändern Sie den Test zusammen mit der Gliederung.

  • Jeder Unterabschnitt ist eine Datei. Unterabschnitte sind Überschriften innerhalb dieser Datei.

  • Das Navigationsmenü zeigt die Abschnitte, die in fetten Großbuchstaben gesetzt sind. Die Teilabschnitte eines Abschnitts sind gefaltet. Sie öffnen sich, wenn der Abschnitt mit seiner Falte Schaltfläche oder wenn eine seiner Seiten angezeigt wird, und die Unterabschnitte eines Unterabschnitts öffnen sich auf die gleiche Weise. Dieses Verhalten wird von html_theme_options in docs/conf.py und von docs/_static/axqua.css definiert.

  • Labels, die mit help- beginnen, markieren die Ziele, die das Plugin von seinen Registerkarten aus öffnet. Behalten Sie sie, wenn eine Seite neu organisiert wird.

  • Die Screenshots des Plugins (docs/img/gui-*.png) werden von python scripts/build_screenshots.py --case <case-file> gemacht, das QGIS ohne Fenster startet, die Stellen, die eine Bildunterschrift erklärt, einrahmt und numeriert und die Ordner des Computers durch neutrale ersetzt. Der Fall muss gebaut werden und einen abgeschlossenen festen Job haben. Das Skript endet mit einem Fehler und benennt die Figur, wenn ein Ort, den eine Beschriftung erklärt, nicht auf dem Bildschirm ist, und es zeichnet die Anzahl der Markierungen jeder Figur in docs/img/gui-screenshots.json auf, die der Test mit den Beschriftungen vergleicht. Führen Sie das Skript nach einer Änderung des Plugins, das ein Bild zeigt, erneut aus.

  • Die UML-Diagramme (docs/img/uml-*.svg) werden aus dem Quellcode mit python scripts/build_uml.py generiert, was Graphviz erfordert. Derselbe Test schlägt fehl, wenn ein Diagramm nicht mehr mit dem Code übereinstimmt. Führen Sie das Skript erneut in diesem Fall aus.