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.

Prise en main

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

The class reference's source files are in the Godot engine repository. We generate the Godot API section of this documentation from them. If you want to update the description of a class, its methods, or properties, read 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 :

  1. La Directives pour la rédaction de documentation. Vous y trouverez des règles et des recommandations pour écrire d'une manière compréhensible par tous.

  2. Les directives relatives au contenu. Elles expliquent les principes que nous suivons pour rédiger la documentation et le type de contenu que nous acceptons.

Contribuer aux changements

Les Pull Requests doivent utiliser la branche master par défaut. Ne faites des demandes de Pull que sur d'autres branches (par exemple 2.1 ou 3.0) si vos modifications ne s'appliquent qu'à cette version spécifique de Godot.

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 :

  1. Cliquez sur le bouton Edit on GitHub.

  2. Sur la page GitHub où vous êtes dirigé, 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".

  3. Modifiez le texte dans l'éditeur de texte.

  4. Au bas de la page Web, résumez les modifications que vous avez apportées et cliquez sur le bouton Propose file change. Veillez à remplacer le caractère générique "Update file.rst" par une description courte mais claire d'une ligne, car il s'agit du titre du commit.

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

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 :

  1. Recherchez les ` questions existantes <https://github.com/godotengine/godot-docs/issues>`_ ou ouvrez-en une nouvelle pour voir si la page est nécessaire.

  2. Assurez-vous qu'il n'y a pas une page qui couvre déjà le sujet.

  3. 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.png

De la même manière, vous pouvez inclure des pièces jointes, comme des ressources servant de support à un didacticiel, en les plaçant dans un dossier files/ à côté du fichier .rst, et en utilisant ce balisage en ligne :

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

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.