Contribuer à la documentation

Ce guide explique comment contribuer à la documentation de Godot, que ce soit en écrivant ou en révisant des pages.

Voir aussi

Si vous souhaitez traduire des pages ou la référence de la classe de l'anglais vers d'autres langues, lisez Localisation de l'éditeur et de la documentation.

Pour commencer

Pour modifier ou créer des pages dans le manuel de référence, vous devez modifier les fichiers .rst dans le dépôt GitHub godot-docs. La modification de ces pages dans une pull request déclenche une reconstruction de la documentation en ligne lors de la fusion.

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.

Avertissement

Les fichiers sources de la référence de classe se trouvent dans le dépôt du moteur Godot. Nous générons la section Class Reference de cette documentation à partir de celles-ci. Si vous souhaitez mettre à jour la description d'une classe, de ses méthodes ou de ses propriétés, lisez Contribuer à la référence des classes.

Qu'est-ce la documentation de Godot

La documentation Godot est conçue comme un manuel de référence complet pour le moteur de jeu Godot. Elle n'est pas censée contenir des didacticiels pas à pas, à l'exception de deux didacticiels de création de jeux dans la section Démarrage.

Nous nous efforçons de rédiger des contenus factuels dans un langage accessible et bien écrit. Pour contribuer, vous devriez également lire :

Writing guidelines. Là, vous trouverez des règles et des recommandations pour écrire d'une manière que tout le monde comprend.
Directives relatives au contenu. Elles expliquent les principes que nous suivons pour écrire la documentation et le type de contenu que nous acceptons.

Contribuer aux changements

Pull requests should use the master branch by default. Only make pull requests against other branches (e.g. 3.6 or 4.2) if your changes only apply to that specific version of Godot. After a pull request is merged into master, it will usually be cherry-picked into the current stable branch by documentation maintainers.

Bien que moins pratique à modifier qu'un wiki, ce dépôt Git est l'endroit où nous écrivons la documentation. Avoir un accès direct aux fichiers sources dans un système de contrôle de révision est un plus pour assurer la qualité de notre documentation.

Modifier des pages existantes

Pour modifier une page existante, localisez son .rst fichier source et ouvrez-le dans votre éditeur de texte préféré. Vous pouvez ensuite commiter les modifications, les pousser vers votre fork et faire une demande de pull. Notez que les pages de classes/ ne doivent pas être modifiées ici. Elles sont générés automatiquement à partir de la référence de classe XML de Godot. Voir Contribuer à la référence des classes pour plus de détails.

Voir aussi

Pour compiler le manuel et tester les modifications sur votre ordinateur, consultez Compiler le manuel avec Sphinx.

Modifier des pages en ligne

Vous pouvez modifier la documentation en ligne en cliquant sur le lien Editer sur GitHub en haut à droite de chaque page.

Vous accédez ainsi à l'éditeur de texte de GitHub. Vous devez avoir un compte GitHub et vous connecter pour l'utiliser. Une fois connecté, vous pouvez proposer des modifications comme suit :

Cliquez sur le bouton Edit on GitHub.
Sur la page GitHub où vous êtes dirigé, assurez vous que la branche actuelle est "Master". Cliquez sur l'icône crayon dans le coin supérieur droit près des boutons Raw, Blame et Delete. Il y a l'info-bulle "Fork this project and edit the file".
Modifiez le texte dans l'éditeur de texte.
Click "Commit changes...", summarize the changes you made and make sure to replace the placeholder "Update file.rst" by a short, but clear one-line description, as this is the commit title. Click the button Propose changes.
Sur les écrans suivants, cliquez sur le bouton Create pull request jusqu'à ce que vous voyiez un message comme Username wants to merge 1 commit into godotengine:master from Username:patch-1.

Note

S'il y a plus de commits que le vôtre dans la pull request, il est probable que votre branche a été créée en utilisant la mauvaise origine, en raison de "master" ne pouvant pas être la branche actuelle dans l'étape 2. Vous devrez rebaser votre branche vers "master" ou créer une nouvelle branche.

Un autre contributeur examinera vos modifications et les intégrera dans la documentation si elles sont bonnes. Il peut également apporter des modifications ou vous demander de le faire avant la fusion.

Ajouter de nouvelles pages

Avant d’ajouter une nouvelle page, assurez-vous qu’elle s’intègre dans la documentation :

Recherchez les ` questions existantes <https://github.com/godotengine/godot-docs/issues>`_ ou ouvrez-en une nouvelle pour voir si la page est nécessaire.
Assurez-vous qu'il n'y a pas une page qui couvre déjà le sujet.
Lisez notre Directives relatives au contenu.

Pour ajouter une nouvelle page, créez un fichier .rst avec un nom significatif dans la section à laquelle vous voulez ajouter un fichier, par exemple tutorials/3d/light_baking.rst.

Vous devez ensuite ajouter votre page au "toctree" (table des matières, par exemple tutorials/3d/index.rst). Ajoutez votre nouveau nom de fichier à la liste sur une nouvelle ligne, en utilisant un chemin relatif et sans extension, par exemple ici light_baking.

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 _doc_insert_your_title_here et le titre doivent correspondre.

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).

Rédigez vos titres comme des phrases simples, sans mettre de majuscules à chaque mot :

Bien : Comprendre les signaux dans Godot
Bien : Comprendre Les Signaux Dans Godot

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

Syntaxe Sphinx et reStructuredText

Consultez le reST Primer de Sphinx et la référence officielle pour des détails sur la syntaxe.

Sphinx utilise des commentaires reST spécifiques pour effectuer des opérations spécifiques, comme la définition de la table des matières (.. toctree::) ou les références croisées de pages. Consultez la documentation officielle de Sphinx pour plus de détails. Pour apprendre à utiliser les directives Sphinx comme .. note:: ou .. seealso::, consultez la documentation des directives Sphinx.

Ajout d'images et de pièces jointes

Pour ajouter des images, veuillez les placer dans un dossier img/ à côté du fichier .rst avec un nom significatif et les inclure dans votre page avec :

.. image:: img/image_name.webp

Alternativement, vous pouvez utiliser la directive figure, qui donne à l'image une bordure contrastée et permet de le centrer sur la page.

.. figure:: img/image_name.webp
    :align: center

You can also include attachments as support material for a tutorial, by placing them into a files/ folder next to the .rst file, and using this inline markup:

:download:`file_name.zip <files/file_name.zip>`

Envisagez d'utiliser le répertoire godot-docs-project-starters <https://github.com/godotengine/godot-docs-project-starters> pour l'hébergement de matériel de support, tels que les modèles de projet et les packs de ressources. Vous pouvez utiliser un lien direct vers l'archive générée à partir de ce dépôt avec le balisage de lien habituel :

`file_name.zip <https://github.com/godotengine/godot-docs-project-starters/releases/download/latest-4.x/file_name.zip>`_

Licence

Cette documentation et chaque page qu'elle contient 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".

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