Contribuer à la référence des classes

La référence de classe est un ensemble d'articles décrivant l'API publique du moteur. Cela comprend des descriptions pour différentes classes, méthodes, propriétés et objets globaux, disponibles pour des scripts. La référence de classe est disponible en ligne, depuis la barre de documentation, et dans l'éditeur Godot, à partir du menu d'aide.

Lorsque le moteur se développe et que les caractéristiques sont ajoutées ou modifiées, certaines parties de la référence de classe deviennent obsolètes et de nouvelles descriptions et exemples doivent être ajoutés. Si les développeurs sont tenus de documenter leur travail dans la référence de classe lors de la soumission d'une pull request, nous ne pouvons pas attendre de chaque programmeur qu'il soit un bon rédacteur technique. Il y a toujours du travail pour les contributeurs comme vous pour polir l'existant et créer des documents de référence manquants.

The source of the class reference

As the class reference is available in two places, online and in the editor, we need to take care to keep things in sync. To achieve this the main Godot repository is picked as the source of truth, and the documentation for the class reference is tracked there.

Avertissement

Vous ne devriez pas éditer les fichiers .rst dans le dossier classes/ du dépôt de documentation. Ces fichiers sont générés automatiquement et sont synchronisés manuellement par les responsables du projet. Continuez à lire pour savoir comment modifier correctement la référence de classe.

Dans le dépôt principal, la référence de classe est stockée dans des fichiers XML, un pour chaque classe exposée ou objet global. La majorité de ces fichiers se trouve dans doc/classes/, mais certains modules contiennent également leur propre documentation. Vous la trouverez dans le répertoire modules/<nom_du_module>/doc_classes/. Pour en savoir plus sur l'édition de fichiers XML, se référer à Class reference primer.

Voir aussi

Pour plus de détails sur l'utilisation de Git et le flux de travail pull request, veuillez consulter la page Flux de travail pour les Pull Request.

Si vous souhaitez traduire la référence de la classe de l'anglais vers une autre langue, consultez Localisation de l'éditeur et de la documentation. Ce guide est aussi disponible en tant que tutoriel vidéo sur YouTube.

Important : Si vous prévoyez d'apporter des modifications importantes, vous devriez créer une issue sur le dépôt godot-docs ou commenter une issue existante. En faisant cela, les autres savent que vous occupez déjà d'une classe donnée.

Que contribuer

L'endroit naturel pour commencer à contribuer est les classes que vous connaissez le plus. Cela garantit que la description ajoutée sera basée sur l'expérience et le savoir-faire nécessaire, pas seulement le nom d'une méthode ou d'une propriété. Nous vous conseillons de ne pas ajouter de descriptions de faible effort, même si cela peut sembler attirant. Ces descriptions occultent le besoin de documentation et sont difficiles à identifier automatiquement.

Voir aussi

Suivre ce principe est important et nous permet de créer des outils pour les contributeurs, comme le suivi de statut de complétion de la référence de classe. Vous pouvez l'utiliser pour trouver rapidement les pages de documentation contenant des descriptions manquantes.

Si vous décidez de documenter une classe, mais ne savez pas ce qu'une méthode particulière fait, aucun problème. Laissez-la pour le moment et listez les méthodes que vous avez passé quand vous faites un pull request de vos changements. Un autre contributeur s'en occupera.

You can still look at the methods' implementation in Godot's source code on GitHub. If you have doubts, feel free to ask on the Godot Forum and Godot Contributors Chat.

Avertissement

À moins que vous n'apportiez des modifications mineures, comme la correction d'une coquille, nous ne recommandons pas d'utiliser l'éditeur web de GitHub pour modifier le XML de la référence de classe. Il manque des fonctionnalités pour bien modifier du XML, comme maintenir les indentations de manière consistantes, et il ne permet pas de modifier les commits basés sur les examens.

De plus, il ne vous permet pas de tester vos modifications dans le moteur ou avec des scripts de validation comme décrit dans Comment modifier la classe XML.

Mettre à jour la référence de classe lorsque vous travaillez sur le moteur

Lorsque vous créez une nouvelle classe ou modifiez l'API du moteur, vous devez générer à nouveau les fichiers XML dans doc/classes/.

Pour ce faire, vous devez d'abord compiler Godot. Consultez la page Introduction au buildsystem pour savoir comment faire. Ensuite, exécutez le binaire Godot compilé depuis le répertoire racine de Godot avec l'option --doctool. Par exemple, si vous êtes sous Linux 64 bits, la commande peut être :

./bin/godot.linuxbsd.editor.x86_64 --doctool

L'ensemble exact de suffixes peut être différent. Lisez attentivement l'article lié pour en savoir plus.

Les fichiers XML dans doc/classes devraient alors être à jour avec les fonctionnalités actuelles de Godot Engine. Vous pouvez ensuite vérifier ce qui a changé en utilisant la commande git diff.

Veuillez inclure uniquement les modifications qui sont pertinentes à votre travail sur l'API dans vos commits. Vous pouvez ignorer les changements dans d'autres fichiers XML en utilisant git checkout, mais envisagez de le déclarer si vous remarquez des fichiers non liés mis à jour. Idéalement, l'exécution de cette commande devrait seulement apporter les changements que vous avez faits vous-même.

Vous devrez ensuite ajouter des descriptions à toutes les entrées nouvellement générées.