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.

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.

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.

Le lien 'Edit on GitHub'

Si vous lisez la documentation sur docs.godotengine.org, vous verrez un lien hypertexte Edit on GitHub en haut à droite de la page. Une fois que vous avez créé un compte GitHub, vous pouvez proposer des modifications à une page que vous êtes en train de lire ainsi :

1. Cliquez sur le bouton Edit on GitHub.

2. Sur la page GitHub où vous êtes dirigé, cliquez sur l'icône du crayon dans le coin supérieur droit près des boutons Raw, Blame et History. Il y a l'info-bulle "Edit the file in a fork of this project" (qui signifie : modifier le fichier dans un fork, c'est à dire une copie, du projet .

3. Effectuez toutes les modifications que vous souhaitez apporter à cette page.

4. Résumez les modifications que vous avez apportées dans le formulaire en bas de la page et cliquez sur le bouton "Propose file change" lorsque vous avez terminé.

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

6. Un réviseur évaluera vos changements et les incorporera dans les documents s'ils sont acceptables. Il peut également vous être demandé d'apporter des modifications à vos changements avant qu'ils ne soient inclus.

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.

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.