Lignes directrices en matière de documentation

Cette page décrit les règles à suivre si vous souhaitez contribuer à Godot Engine en écrivant ou en examinant la documentation, ou en traduisant la documentation existante. Aussi, jetez un oeil au README de la godot-docs GitHub repository et la docs front page sur les étapes à suivre et comment contacter l’équipe de docs.

Comment contribuer

La création ou la modification de pages de documentation se fait principalement via le dépôt GitHub de godot-docs. La documentation HTML (ou PDF et EPUB) est générée à partir des fichiers .rst (reStructuredText markup language) de ce dépôt. La modification de ces pages dans une pull request et leur fusion déclenchera une reconstruction de la documentation en ligne.

Voir aussi

Pour plus de détails sur l’utilisation de Git et sur le flux de travail des Pull Requests, veuillez vous référer à la page Flux de travail pour les Pull Request. La plupart de ce qu’elle décrit concernant le dépôt principal godotengine/godot est également valable pour le dépôt docs.

Le fichier README.md contient toutes les informations nécessaires pour vous aider à démarrer, veuillez le lire. Il contient notamment quelques conseils et astuces et des liens vers des documents de référence sur le langage reStructuredText.

Avertissement

Si vous souhaitez modifier la référence API, veuillez noter que cela ne doit pas être fait dans le dépôt godot-docs. A la place, vous devez éditer les fichiers XML doc/classes/* du dépôt principal de Godot. Ces fichiers sont ensuite utilisés pour générer la documentation de l’éditeur ainsi que la référence API des documents en ligne. Plus d’informations ici : Contribuer à la référence des classes (API).

Qu’est-ce qui fait une bonne documentation ?

La documentation doit être bien rédigée dans un anglais simple, en utilisant des phrases bien formées et différents niveaux de sections et de sous-sections. Elle doit être claire et objective. Consultez également les Directives pour la rédaction de documentation.

Nous différencions les pages de tutoriel des autres pages de documentation par ces définitions :

  • Tutoriel : une page visant à expliquer comment utiliser un ou plusieurs concepts dans l’éditeur de scripts ou dans le but d’atteindre un objectif spécifique, avec un objectif d’apprentissage (par exemple, « Faire un simple 2d jeu de Pong », « l’Application de forces à un objet »).
  • Documentation : une page décrivant précisément un seul et unique concept à la fois, si possible de manière exhaustive (par exemple la liste des méthodes de la classe Sprite, ou un aperçu de la gestion des inputs (entrées) dans Godot).

Vous êtes libre de rédiger le type de documentation que vous souhaitez, pour autant que vous respectiez les règles suivantes (et celles du dépôt).

Titres

Commencez toujours les pages par leur titre et un nom de référence Sphinx :

.. _doc_insert_your_title_here:

Insert your title here
======================

La référence permet un lien vers cette page en utilisant le format :ref:, par exemple :ref:`doc_insérer_votre_titre_ici` aurait un lien pour l’exemple ci-dessus page (notez l’absence de préfixe tiret du bas “_” dans la référence).

Évitez également les titres American CamelCase : le premier mot du titre doit commencer par une lettre en majuscule, et tous les mots suivants ne doivent pas commencer par cette lettre. Voici un bon exemple :

  • Insérez votre titre ici

Et ceci est un mauvais exemple :

  • Insérez Votre Titre Ici

Seuls les noms de projets, de personnes et de classes de nœuds doivent avoir une première lettre en majuscule.

Traduction de pages existantes

Vous pouvez aider à traduire la documentation officielle de Godot sur notre Hosted Weblate.

Translation state

Il existe également le dépôt officiel Godot i18n où vous pouvez voir quand les données ont été synchronisées pour la dernière fois.

Licence

Tout le contenu de la documentation est publié sous les termes de la licence Creative Commons Attribution 3.0 license (CC-BY-3.0), avec attribution à « Juan Linietsky, Ariel Manzur et la communauté Godot Engine ».

En contribuant à la documentation sur le dépôt GitHub, vous acceptez que vos modifications soient distribuées sous cette licence.