Contribuer à la documentation de Weblate

Bienvenue si vous souhaitez améliorer la page de documentation de votre choix. Faites-le facilement en cliquant sur le bouton Editer dans GitHub dans le coin supérieur droit de la page.

Documentation guidelines

Veuillez respecter ces règles tout au long de votre rédaction :

  1. Ne supprimez pas la partie valide de la documentation.

  2. Utilisez un langage clair et facilement compréhensible. Vous rédigez des documents techniques et non des poèmes. Tous les lecteurs de documents n’en maîtrisent pas forcément la langue, rappelez-vous en.

  3. N’hésitez pas à vous renseigner quand vous n’êtes pas certain. Si vous avez des questions sur une fonctionnalité alors que vous rédigez, ne modifiez pas la documentation avant d’avoir obtenu une réponse. Cela signifie : soit vous modifiez, soit vous vous interrogez, mais vous ne faites pas les deux en même temps.

  4. Vérifiez vos modifications en réalisant les actions décrites en suivant les documents.

  5. Faites vos PR sur de petites modifications dans le code pour qu’elles soient plus faciles et plus rapides à relire et à fusionner.

  6. Si vous souhaitez réécrire ou modifier la structure d’un gros article, faites le en deux étapes :

    1. Réécrire

    2. Une fois que la réécriture a été relue, affinée, et intégrée, modifiez la structure des paragraphes dans un autre PR.

Building the documentation locally

Documentation can be also edited and built locally, the Python requirements are in the docs dependency group in pyproject.toml. If you already use the full development environment, uv sync --all-extras --dev is enough. For documentation work only, uv sync --group docs is sufficient.

The recommended local workflow is:

make -C docs update-docs
./ci/run-docs

The ci/run-docs wrapper builds the documentation with warnings treated as errors.

Indication

You will also need graphviz installed to build the documentation.

Translating the documentation

Vous pouvez traduire la documentation.

Updating generated documentation snippets

Several documentation sections use templates generated from the code. The preferred way to refresh them is:

make -C docs update-docs

This target regenerates the snippets currently used by the documentation, including:

  • add-on events, built-in add-ons, and common add-on parameters

  • machine translation services

  • file format parameters and file format feature tables

  • permissions and built-in roles

  • checks and check flags

Keep manually maintained text in the parent documentation page rather than adding it to autogenerated snippets. For example, Extensions includes three generated files for events, built-in add-ons, and common add-on parameters, while obsolete add-ons are maintained directly in the page.

If you need to regenerate only one part, the individual management commands are documented in Commandes de gestion, and the exact commands used by update-docs are listed in docs/Makefile.