Important

La traduction est le fruit d’un effort communautaire auquel vous pouvez vous joindre. Cette page est actuellement traduite à 100.00%.

19. Annexe : Contribution à ce manuel

Pour ajouter du contenu à ce cours, vous devez suivre les recommandations dans cette annexe. Vous n’êtes pas autorisé à changer les conditions dans ces annexes, sauf pour des clarifications. C’est pour s’assurer que la qualité et le contenu de ce manuel puissent être maintenus.

19.1. Téléchargement des ressources

La source de ce document est disponible sur GitHub. Consultez GitHub.com pour les instructions d’utilisation du système de contrôle de versionnement git.

19.2. Format du Manuel

Ce manuel est écrit en utilisant Sphinx, un générateur de documentation sous Python utilisant le langage de balise reStructuredText. Les instructions sur l’utilisation de ces outils sont disponibles sur leurs sites respectifs.

19.3. Ajout d’un module

Pour ajouter un nouveau module :

  1. Créez tout d’abord un nouveau répertoire (directement sous le plus haut niveau du répertoire qgis-training-manual) avec le nom du nouveau module.

  2. Sous ce nouveau répertoire, créez un fichier appelé index.rst. Pour l’instant laissez le fichier vierge.

  3. Ouvrez le fichier index.rst sous le plus haut niveau du répertoire. Ses premières lignes sont

    .. toctree::
   :maxdepth: 2

   foreword/index
   introduction/index

Vous remarquerez que c’est une liste de noms de répertoires, suivis par le nom index. Cela dirige le fichier index au plus haut niveau dans chaque répertoire. L’ordre dans lequel ils sont listés détermine l’ordre dans lequel ils apparaîtront dans le document.

  1. Ajoutez le nom de votre nouveau module (c’est-à-dire le nom que vous avez donné au nouveau répertoire), suivi par /index, à cette liste, là où vous voulez que votre module apparaisse.

  2. Souvenez-vous de garder l’ordre des modules logique, de telle sorte que les modules suivants s’appuient sur la connaissance présentée dans les modules précédents.

  3. Ouvrez le fichier index de votre nouveau module ([module name]/index.rst).

  4. En haut de la page, créez l’en-tête du module:

    1. écrivez une première ligne d’astérisques (*)

    2. Poursuivez avec une ligne contenant la balise Module:, suivi du nom de votre module

    3. Terminez avec une autre ligne du même nombre d’astérisques.

    Note

    La ligne supérieur et la ligne inférieur d’astérisques ne doivent pas être plus courte que la ligne contenant le nom du module.

  5. Laissez une ligne ouverte sous ça.

  6. Écrivez un court paragraphe expliquant la fonction et le contenu de ce module.

  7. Laissez une ligne ouverte, puis ajoutez le texte suivant:

    .. toctree::
   :maxdepth: 2

   lesson1
   lesson2

    … où :lesson1, lesson2, etc., sont les noms de vos leçons prévues.

Le fichier index au niveau du module ressemblera à ceci :

*******************************************************************************
Module: Module Name
*******************************************************************************

Short paragraph describing the module.

.. toctree::
   :maxdepth: 2

   lesson1
   lesson2

19.4. Ajout d’une leçon

Pour ajouter une leçon à un module existant ou non:

  1. Ouvrez le répertoire du module.

  2. Ouvre le fichier index.rst (créé ci-dessus dans le cas de nouveaux modules)

  3. Assurez-vous que le nom de la leçon prévue est listé sous la directive toctree, comme montré ci-dessous.

  4. Créez un nouveau fichier sous le répertoire du module.

  5. Nommez ce fichier exactement de la même manière que le nom que vous avez fourni dans le fichier index.rst du module, et ajoutez l’extension .rst.

Note

À des fins d’édition, un fichier .rst fonctionne exactement comme un fichier texte normal (.txt).

  1. Pour commencer à écrire la leçon, écrivez l’expression de balisage Lesson:, suivie du nom de la leçon.

  2. Sur la ligne suivante, écrivez une ligne de signe égal (=), pas plus courte que le titre de la leçon.

  3. Laissez une ligne ouverte après ceci.

  4. Écrivez une courte description du but recherché de la leçon.

  5. Incluez une introduction générale au sujet. Regardez les leçons existantes dans ce manuel pour les exemples.

  6. Sous cela, commencez un nouveau paragraphe, débutant avec cette phrase

    **The goal for this lesson:**

  7. Expliquez brièvement le résultat escompté à la fin de cette leçon.

  8. Si vous ne pouvez pas décrire le but de la leçon en une ou deux phrases, envisagez de couper le sujet en plusieurs leçons.

Chaque leçon sera subdivisée en plusieurs sections, qui seront traitées après.

19.5. Ajout d’une nouvelle section

Il existe deux types de sections: « Étape par étape » et « Essayez vous-même ».

  • Une section « Etape par étape » est un ensemble détaillé d’instructions destinées à apprendre au lecteur comment utiliser tel ou tel aspect de QGIS. Cela se fait habituellement en donnant les instructions clic-par-clic aussi claires que possible, entrecoupées de captures d’écran.

  • Une section « Essayez vous-même » assigne au lecteur une petite mission à réaliser de lui-même. Elle est généralement associée à une entrée dans la feuille de réponses à la fin de la documentation, qui va montrer ou expliquer comment faire cet exercice, et affichera le résultat escompté si possible.

Chaque section est accompagnée d’un niveau de difficulté. Une section facile est désignée par ★☆☆, modérée par ★★☆ et avancée par ★★★.

19.5.1. Ajout d’une section « Etape par étape »

  1. Pour commencer cette section, écrivez la balise du niveau de difficulté prévu (comme montré ci-dessus).

  2. Laissez un espace puis écrivez Follow Along:.

  3. Laissez un autre espace et écrivez le nom de la section (utilisez seulement une initiation en majuscule, ainsi que les capitales pour les noms propres).

  4. Sur la ligne suivante, écrivez une ligne de signe égal (=), pas plus courte que le titre de la section.

  5. Écrivez une courte introduction à la section, expliquant ses objectifs. Puis donnez des instructions détaillées (clic-pa-clic) sur la procédure à être démontrée.

  6. Dans chaque section, incluez des liens internes, des liens externes et des captures d’écran au besoin.

  7. Essayez de clore toute section avec un court paragraphe qui la conclut et fait naturellement un lien vers la section suivante, si possible.

19.5.2. Ajout d’une section « Essayez vous-même »

  1. Pour commencer cette section, écrivez la balise du niveau de difficulté prévu (comme montré ci-dessus).

  2. Laissez un espace puis écrivez Essayez vous-même:.

  3. Sur la ligne suivante, écrivez une ligne de signe égal (=), pas plus courte que le titre de la section.

  4. Expliquez l’exercice que vous voulez que le lecteur fasse. Référez-vous aux sections, leçons ou modules précédents si nécessaire.

  5. Incluez des captures d’écran pour clarifier les exigences si une description textuelle n’est pas claire.

Dans la plupart des cas, vous voudrez donner une réponse sur la façon de compléter la consigne donnée dans cette section. Pour faire cela, vous aurez besoin de créer un bloc de réponse sous les instructions.

  1. Tout d’abord, créez un widget pliable qui contient la réponse:

    .. admonition:: Answer
   :class: dropdown

  2. En gardant l’indentation par rapport au bloc précédent, écrivez les instructions sur la manière de répondre à la consigne, en utilisant des images et des liens si nécessaire.

19.6. Ajout d’une conclusion

Pour terminer la leçon:

  1. Écrivez l’expression Conclusion, suivie d’une nouvelle ligne de tirets (-).

  2. Écrivez une conclusion pour la leçon, expliquant les concepts traités dans la leçon.

19.7. Ajout d’une section Pour aller plus loin

Cette section est optionnelle.

  • Écrivez la phrase Lectures complémentaires, suivie d’une nouvelle ligne de tirets/moins (-).

  • Incluez des liens vers des sites externes appropriés.

19.8. Ajout d’une section La suite ?

  1. Écrivez la phrase Quelle est la prochaine étape ?, suivie d’une nouvelle ligne de tirets/moins (-).

  2. Expliquez comment cette leçon a préparé les étudiants à la prochaine leçon ou au prochain module.

  3. Pensez à changer la section « La suite ? » de la précédente leçon si nécessaire, afin qu’elle fasse référence à votre leçon. Cela sera nécessaire si vous avez inséré une nouvelle leçon entre les leçons déjà existantes, ou après une leçon existante.

19.9. Utilisation des balises

Pour adopter les standards de ce document, vous devrez ajouter des balises standards à votre texte.

19.9.1. Nouveaux concepts

Si vous êtes en train d’expliquer un nouveau concept, vous devrez écrire le nom du nouveau concept en italique en l’enfermant entre des astérisques (*).

This sample text shows how to introduce a *new concept*.

19.9.2. Accentuation

  • Pour accentuer un terme important qui n’est pas un nouveau concept, écrivez-le en gras en l’enfermant entre des doubles astérisques (**).

  • Utilisez cela avec modération ! Si vous l’utilisez trop, il peut sembler au lecteur que vous criez ou que vous êtes condescendant.

This sample text shows how to use **emphasis** in a sentence. Include the
punctuation mark if it is followed by a **comma,** or at the **end of the
sentence.**

19.9.3. Images

  • Lorsque vous ajoutez une image, enregistrez-la dans un dossier img à côté du fichier de la leçon.

  • Incluez-la dans le document comme ceci

    .. figure:: img/image_file.extension
   :align: center

  • Souvenez-vous de laisser une ligne vide en-dessus et en-dessous de la balise de l’image.

19.9.6. Utilisant du texte mono-espacé

  • Lorsque vous écrivez un texte qui indique que l’utilisateur doit saisir un emplacement de fichiers ou le nom d’un élément de base de données tel qu’une table ou un nom de colonne, vous devez l’écrire en monospaced text. Par exemple:

    Enter the following path in the text box: ``path/to/file``.

19.9.7. Étiqueter les éléments de l’interface

  • Quand vous faites référence à un élément de l’interface, comme un bouton, vous devez écrire son nom dans le format des éléments de l’interface. Par exemple :

    To access this tool, click on the :guilabel:`Tool Name` button.

  • Cela s’applique également si vous mentionnez le nom d’un outil sans obliger l’utilisateur à cliquer sur un bouton.

19.9.9. Ajout de notes

  • Vous devrez peut-être rédiger une note dans le texte qui donne plus de détails qui ne peuvent faire partie du contenu général de la leçon. C’est la balise:

    [Normal paragraph.]

.. note:: Note text.
  New line within note.

  New paragraph within note.

[Unindented text resumes normal paragraph.]

19.9.10. Ajouter une note sur l’auteur ou le sponsor

Si vous écrivez un nouveau module, une nouvelle leçon ou une section par le financement d’un sponsor, vous devez y inclure un message de leur choix. Cela indique au lecteur le nom du sponsor et il doit apparaître en dessous de l’entête du module, de la leçon ou de la section sponsorisé(e). Néanmoins, il ne s’agit pas d’une publicité pour leur entreprise.

Si vous vous êtes porté volontaire pour écrire un module, une leçon ou une section et que vous n’être pas patronné, vous pouvez inclure une note sur l’auteur en dessous de l’élément que vous avez créé. Cela doit prendre la forme ``Ce/Cette [module/leçon/section] a été rédigé/e par [nom de l’auteur]`. N’ajoutez pas plus de texte, ni d’informations de contact, etc. Ces détails sont à ajouter dans la section « Contributions » de l’avant-propos, avec les noms des parties que vous avez ajoutées. SI vous avez seulement réalisé des améliorations, corrections ou ajouts, vous pouvez être listé dans les éditeurs.

19.10. Merci !

Merci de votre contribution à ce projet ! En contribuant, vous rendez QGIS plus accessible aux utilisateurs et ajoutez de la valeur au projet QGIS dans son ensemble.