Cette page a été traduite automatiquement de l’anglais et peut contenir des erreurs. Original en anglais

Construction de la documentation

La documentation est écrite dans reStructuredText et construite avec Sphinx. La construction ne nécessite que Sphinx et le thème. Les paquets dont aXqua a besoin au moment de l’exécution sont remplacés par des placeholders pendant la construction (autodoc_mock_imports in docs/conf.py).

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

Ouvrir docs/_build/html/index.html dans un navigateur Web pour lire le résultat. La sortie dossier docs/_build/ est exclue du contrôle de la version.

Langues et publication

La documentation est publiée deux fois. Read the Docs construit les pages en anglais de la branche main par elle-même, avec les commandes ci-dessus, et les sert à axqua.readthedocs.io. GitHub Pages sert les pages en anglais à axqua.eu en même temps qu’une traduction allemande à axqua.eu/de/ et une traduction française à axqua.eu/fr/; axqua.de et axqua.ch vers les pages en allemand et axqua.fr vers les pages en français. Un bouton en haut à droite de chaque page change de langue. Les pages allemandes et françaises sont des traductions automatiques, et chaque page le dit.

Les traductions sont conservées par page à docs/locale/<language>/LC_MESSAGES/, dans le format gettext que Sphinx lit. Ils nécessitent un environnement séparé avec le moteur de traduction hors ligne Argos Translate, et ils sont publiés avec un script dans le dossier racine du dépôt :

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 construit les pages en anglais, traduit seulement les paragraphes qui sont nouveaux ou modifiés depuis la dernière publication, construit les pages en allemand et en français, et copie le résultat dans l’arbre de travail de la branche gh-pages. Avec --push, il engage les traductions actualisées sur main, pousse main (qui met également à jour Read the Docs), et engage et pousse gh-pages. Elle refuse de publier des modifications non engagées.

Un glossaire des termes techniques pour chaque langue (docs/i18n/glossary.de.tsv et glossary.fr.tsv) fait que le moteur utilise les termes du génie hydraulique, par exemple Abflusskurve et courbe de tarage pour courbe de tarage. Les étiquettes de l’extension dans les astérisques uniques, le code dans les doubles citations, et les titres des papiers dans les listes de références ne sont jamais traduits. Une traduction qui a été corrigée à la main dans un catalogue est conservée tant que le texte anglais ne change pas. docs/i18n/README.md explique les glossaires, les corrections à la main et les paramètres des scripts.

Règles de la structure

  • Les grandes lignes des sections et des sous-sections sont fixées et vérifiées par le test tests/test_docs_outline.py. Modifier le test avec le contour.

  • Chaque sous-section est un seul dossier. Les sous-sections sont des en-têtes dans ce fichier.

  • Le menu de navigation montre les sections, qui sont définies en caractères majuscules gras. Les sous-sections d’une section sont repliées. Ils s’ouvrent lorsque la section est ouverte avec son pli bouton ou lorsque l’une de ses pages est affichée, et les sous-sections d’une sous-section s’ouvrent de la même manière. Ce comportement est défini par html_theme_options à docs/conf.py et par docs/_static/axqua.css.

  • Les étiquettes qui commencent par help- marquent les cibles que l’extension ouvre depuis ses onglets. Gardez-les quand une page est réorganisée.

  • Les captures d’écran de l’extension (docs/img/gui-*.png) sont prises par python scripts/build_screenshots.py --case <case-file>, qui démarre QGIS sans fenêtre, cadres et chiffres les endroits qu’une légende explique, et remplace les dossiers de l’ordinateur par des dossiers neutres. Le cas doit être construit et avoir une tâche stable. Le script se termine par une erreur et nomme la figure si un endroit qu’une légende explique n’est pas à l’écran, et il enregistre le nombre de marques de chaque figure dans docs/img/gui-screenshots.json, que le test compare avec les légendes. Exécutez à nouveau le script après une modification à l’extension qu’une image affiche.

  • Les diagrammes UML (docs/img/uml-*.svg) sont générés à partir du code source avec python scripts/build_uml.py, ce qui nécessite Graphviz. Le même test échoue si un diagramme ne correspond plus au code. Exécutez encore le script dans ce cas.