Contribuer¶
Les règles de contribution (CLA, sign-off, vérifications, contributions assistées par IA) sont dans CONTRIBUTING.md. Cette page traite de la documentation.
La documentation change avec le code¶
Une pull request qui change ce que les utilisateurs voient ou configurent (un écran, une adresse, une opération d’API, un réglage) met à jour cette documentation dans la même pull request. Le contrôle Documentation updated échoue quand un tel changement arrive sans aucune modification sous docs/. Quand aucune page n’est concernée, le mainteneur ajoute l’étiquette no-docs-needed à la pull request, et le contrôle passe.
Construire le site en local¶
uv sync --locked --group docs
uv run playwright install --only-shell chromium # once
uv run python scripts/docs_screenshots.py
uv run python scripts/build_docs.py
uv run python scripts/check_docs_site.py docs/_build/site
uv run python scripts/check_docs_design.py docs/_build/site
Le site est dans docs/_build/site/, l’anglais à sa racine et le français sous fr/ ; ouvrez docs/_build/site/index.html dans un navigateur. La construction est stricte : le moindre avertissement, comme une référence cassée, la fait échouer. check_docs_design.py vérifie le contraste de chaque page dans les thèmes clair et sombre, le focus clavier et la réduction des animations, et enregistre des captures de quelques pages dans docs/_build/site-screenshots/.
Les captures d’écran viennent d’une instance de démonstration aux données générées, en anglais et en français, sur ordinateur et sur téléphone. Elles ne sont pas commitées : le script les refait avant chaque construction.
Traductions¶
Les pages sont écrites en anglais. Leurs traductions françaises sont des catalogues gettext, un par page, dans docs/locale/fr/LC_MESSAGES/. Après avoir modifié une page, mettez les catalogues à jour, puis traduisez les nouvelles chaînes dans les fichiers .po :
uv run python scripts/build_docs.py --update-catalogs
Une chaîne sans traduction s’affiche en anglais, et la page française indique alors qu’elle n’est pas entièrement traduite. La construction échoue quand un catalogue manque d’une chaîne de sa page, afin que les catalogues ne prennent jamais de retard sur les pages.