Contributing to the class reference

Note

Ce guide est disponible sous forme de tutoriel vidéo sur YouTube.

Godot est livré avec de nombreux nœuds et singletons pour vous aider à développer vos jeux. Chacun est une classe, documentée dans le fichier class reference. Cette référence est essentielle pour toute personne apprenant le moteur : elle est disponible en ligne et dans le moteur.

Mais il est incomplet. Certaines méthodes, variables et signaux n'ont pas de description. D'autres ont changé avec les dernières versions et nécessitent des mises à jour. Les développeurs ne peuvent pas écrire toute la référence par eux-mêmes. Godot a besoin de votre contribution, et de celle de nous tous.

Important : Si vous prévoyez d'apporter des changements plus importants ou une contribution plus substantielle, il est généralement judicieux de créer une issue (ou un commentaire dans une issue existante) pour en informer les autres afin qu'ils ne commencent pas à travailler sur la même chose.

Voir aussi

Vous ne savez pas par où commencer pour contribuer ? Jetez un coup d'œil à l'état d'achèvement actuel des références de classe ici.

Comment contribuer

La référence de classe se trouve dans les fichiers XML suivants, dans le dépôt GitHub de Godot : doc/classes/.

Il y a 5 étapes pour mettre à jour la référence de classe (guide complet ci-dessous) :

  1. Fork Dépôt de Godot
  2. Clonez votre fork sur votre ordinateur
  3. Modifier le fichier de classe dans doc/classes/ pour rédiger la documentation
  4. Commitez vos changements et pushez les dans votre fork
  5. Faire une pull request sur le dépôt Godot

Avertissement

Utilisez toujours ces fichiers XML pour modifier la référence de l'API. Ne modifiez pas les fichiers .rst générés dans la documentation en ligne, hébergés dans le dépôt godot-docs.

Débuter avec Github

Si vous débutez avec Git et GitHub, ce guide vous aidera à démarrer. Vous apprendrez à :

  • Fork et clone du dépôt de Godot
  • Tenez votre fork à jour avec les autres contributeurs
  • Créez une pull request pour que vos améliorations se retrouvent dans la documentations officielles

Note

Si vous êtes nouveau sur Git, le système de contrôle de version que Godot utilise, consultez le guide interactif GitHub's interactive guide. Vous y apprendrez le vocabulaire essentiel et vous vous familiariserez avec l'outil.

Fork Godot

Fork le moteur Godot dans votre propre dépôt GitHub.

Clonez le dépôt sur votre ordinateur :

git clone https://github.com/your_name/godot.git

Créez une nouvelle branche pour effectuer vos changements. Cela facilite grandement la synchronisation de vos améliorations avec les autres auteurs de documentation. Il est également plus facile de nettoyer votre dépôt si vous rencontrez des problèmes avec Git.

git checkout -b your-new-branch-name

La nouvelle branche est la même que votre branche principale, jusqu'à ce que vous commenciez à écrire de la documentation API. Dans le dossier doc/, vous trouverez la référence de la classe.

Comment tenir à jour votre clone local

D'autres écrivains contribuent à la documentation de Godot. Votre dépôt local sera à la traîne et vous devrez le synchroniser. Surtout si d'autres contributeurs mettent à jour la référence de classe pendant que vous travaillez dessus.

Ajoutez d'abord un git remote upstream avec lequel travailler. Les remotes(distants) sont des liens vers des dépôts en ligne où vous pouvez télécharger de nouveaux fichiers.

git remote add upstream https://github.com/godotengine/godot

Vous pouvez consulter la liste de tous les serveurs distants avec :

git remote -v

Vous devriez en avoir deux : origin, votre fork sur GitHub, que Git ajoute par défaut, et upstream, que vous venez d'ajouter :

origin  https://github.com/your_name/godot.git (fetch)
origin  https://github.com/your_name/godot.git (push)
upstream        https://github.com/godotengine/godot.git (fetch)
upstream        https://github.com/godotengine/godot.git (push)

Chaque fois que vous voulez synchroniser votre branche avec l'état du dépôt en amont(upstream), entrez :

git pull --rebase upstream master

Cette commande va d'abord fetch, ou télécharger la dernière version du dépôt Godot. Ensuite, elle appliquera à nouveau vos modifications locales par dessus.

Si vous avez fait des changements que vous ne voulez pas garder dans votre branche locale, utilisez plutôt les commandes suivantes :

git fetch upstream
git reset --hard upstream master

Avertissement : La commande ci-dessus va remettre votre branche dans l'état de la branche upstream master. Elle supprimera tous les changements locaux. Assurez-vous de n'exécuter cette commande qu'avant d'effectuer des changements importants.

Une autre option consiste à supprimer la branche sur laquelle vous travaillez, à synchroniser la branche maître(master) avec le dépôt Godot et à créer une nouvelle branche :

git checkout master
git branch -d your-new-branch-name
git pull --rebase upstream master
git checkout -b your-new-branch-name

Si vous vous sentez perdu, venez sur nos canaux IRC et demandez de l'aide. Des utilisateurs expérimentés de Git vous donneront un coup de main.

Mise à jour du modèle de documentation

Lorsque des classes sont modifiées dans le code source, le modèle de documentation peut devenir obsolète. Pour vous assurer que vous éditez une version à jour, vous devez d'abord compiler Godot (vous pouvez suivre la page Introduction au buildsystem), puis exécuter la commande suivante (Linux 64 bits) :

./bin/godot.x11.tools.64 --doctool .

Les fichiers XML dans doc/classes devraient alors être à jour avec les fonctionnalités actuelles du moteur Godot. Vous pouvez alors vérifier ce qui a changé en utilisant la commande git diff. S'il y a des changements dans d'autres classes que celle que vous envisagez de documenter, veuillez d'abord valider ces changements avant de commencer à modifier le modèle :

git add doc/classes/*.xml
git commit -m "Sync classes reference template with current code base"

Vous êtes maintenant prêt à éditer ce fichier pour ajouter des choses.

Note: Si cela a été fait récemment par un autre contributeur, vous n'avez pas besoin de passer par ces étapes (sauf si vous savez que la classe que vous prévoyez d'éditer a été modifiée récemment).

Push et faire une pull request pour vos changements

Une fois vos modifications terminées, poussez vos modifications sur votre dépôt GitHub :

git add doc/classes/<edited_file>.xml
git commit -m "Explain your modifications."
git push

Une fois que c'est fait, vous pouvez demander une Pull Request via l'interface utilisateur GitHub de votre fork Godot.

Avertissement

Bien que vous puissiez modifier des fichiers sur GitHub, ce n'est pas recommandé. Comme des centaines de contributeurs travaillent sur Godot, l'historique de Git doit rester propre. Chaque commit doit regrouper toutes les améliorations liées que vous apportez à la référence de classe, une nouvelle fonctionnalité, des corrections de bugs ... Lorsque vous éditez à partir de GitHub, il créera une nouvelle branche et une Pull Request à chaque fois que vous voudrez l'enregistrer. Si quelques jours s'écoulent avant que vos modifications ne soient examinées, vous ne pourrez pas effectuer proprement la mise à jour vers la dernière version du dépôt. En outre, il est plus difficile de conserver les idents de GitHub propres. Et ils sont très importants dans la documentation.

TL;DR : Si vous ne savez pas exactement ce que vous faites, ne modifiez pas les fichiers de GitHub.

Comment modifier la classe XML

Editez le fichier de la classe choisie dans doc/classes/ pour mettre à jour la référence de la classe. Le dossier contient un fichier XML pour chaque classe. Le fichier XML énumère les constantes et les méthodes que vous trouverez dans la référence de classe. Godot génère et met à jour le XML automatiquement.

Edit it using your favorite text editor. If you use a code editor, make sure that it doesn't change the indent style: tabs for the XML, and 4 spaces inside BBCode-style blocks. More on that below.

Si vous avez besoin de vérifier que les modifications que vous avez faites sont correctes dans la documentation générée, compilez Godot comme décrit ici, exécutez l'éditeur et ouvrez l'aide pour la page que vous avez modifiée.

Comment écrire la référence de classe

Chaque classe a une description brève et une description longue. La description brève se trouve toujours en haut de la page, tandis que la description complète se trouve en dessous de la liste des méthodes, des variables et des constantes. Les méthodes, les variables membres, les constantes et les signaux se trouvent dans des catégories séparées ou des nœuds XML. Pour chacun d'eux, apprenez comment ils fonctionnent dans le code source de Godot, et remplissez leur <description>.

Notre travail consiste à ajouter le texte manquant entre ces marques :

  • <description></description>
  • <brief_description></brief_description>
  • <constant></constant>
  • <method></method>
  • <member></member>
  • <signal></signal>

Écrivez dans un langage clair et simple. Suivez toujours les directives writing guidelines pour garder vos descriptions courtes et faciles à lire. Ne laissez pas de lignes vides dans les descriptions : chaque ligne du fichier XML donnera lieu à un nouveau paragraphe.

Voici à quoi ressemble une classe en XML :

<class name="Node2D" inherits="CanvasItem" category="Core">
    <brief_description>
        Base node for 2D system.
    </brief_description>
    <description>
        Base node for 2D system. Node2D contains a position, rotation and scale, which is used to position and animate. It can alternatively be used with a custom 2D transform ([Matrix32]). A tree of Node2Ds allows complex hierarchies for animation and positioning.
    </description>
    <methods>
        <method name="set_pos">
            <argument index="0" name="pos" type="Vector2">
            </argument>
            <description>
                Sets the position of the 2D node.
            </description>
        </method>
        [...]
        <method name="edit_set_pivot">
            <argument index="0" name="arg0" type="Vector2">
            </argument>
            <description>
            </description>
        </method>
    </methods>
    <members>
        <member name="global_position" type="Vector2" setter="set_global_position" getter="get_global_position" brief="">
        </member>
        [...]
        <member name="z_as_relative" type="bool" setter="set_z_as_relative" getter="is_z_relative" brief="">
        </member>
    </members>
    <constants>
    </constants>
</class>

Utilisez un éditeur de code comme Vim, Atom, Code, Notepad++ ou autre pour éditer le fichier rapidement. Utilisez la fonction de recherche pour trouver rapidement des classes.

Improve formatting with BBCode style tags

Godot's class reference supports BBCode-like tags. They add nice formatting to the text. Here's the list of available tags:

Balise Effet Utilisation Résultat
[Class] Lier une classe Déplacez le [Sprite]. Déplacez le Sprite.
[method methodname] Lien vers une méthode dans cette classe Appelez [method hide]. Voir hide.
[method Class.methodname] Lien vers la méthode d'une autre classe Appelez [method Spatial.hide]. Voir hide.
[member membername] Lien vers un membre dans cette classe Obtenir [member scale]. Obtenir scale.
[member Class.membername] Lien vers un membre d'une autre classe Obtenir [member Node2D.scale]. Obtenir scale.
[signal signalname] Lien vers un signal dans cette classe Émettre [signal renamed]. Émettre renamed.
[signal Class.signalname] Lien vers le signal d'une autre classe Émettre [signal Node.renamed]. Émettre renamed.
[b] [/b] Gras Du texte en [b]gras[/b]. Du texte en gras.
[i] [/i] Italique Du texte en [i]italique[/i]. Du texte italique.
[code] [/code] Monospace Du texte [code]monospace[/code]. Du texte monospace.
[kbd] [/kbd] Raccourci clavier/souris Des touches [kbd]Ctrl + C[/kbd]. Des touches Ctrl + C.
[codeblock] [/codeblock] Bloc multiligne préformaté Voir ci-dessous. Voir ci-dessous.

Utiliser [codeblock] pour des blocs de code préformatés. À l'intérieur de [codeblock], utiliser toujours quatre espaces pour l'indentation (l'analyseur supprimera les tabulations). Par exemple :

[codeblock]
func _ready():
    var sprite = get_node("Sprite")
    print(sprite.get_pos())
[/codeblock]

S'affichera comme cela :

func _ready():
    var sprite = get_node("Sprite")
    print(sprite.get_pos())

Je ne sais pas ce que cette méthode fait !

Aucun problème. Laissez-le derrière et lister les méthodes que vous avez passé quand vous faites un pull request de vos changements. Un autre contributeur s'en occupera.

Vous pouvez toujours regarder l'implémentation des méthodes dans le code source de Godot sur GitHub. Ainsi, si vous avez des doutes, n'hésitez pas à poser des questions sur le site web Q&A site et sur IRC (freenode, #godotengine).

Localisation

La documentation peut être traduite dans n'importe quelle langue sur Hosted Weblate.

Les chaînes traduites sont synchronisées manuellement par les responsables de la documentation dans le dossier godot-docs-l10n.

Les langues avec un bon niveau d'achèvement ont leurs propres instances localisées de ReadTheDocs. Ouvrez un problème sur le dépôt godot-docs-l10n si vous pensez qu'un nouveau langage est assez complet pour obtenir sa propre instance.