Outdated version of the documentation. Find the latest one here.

19. Annexe : Contribution à ce manuel

Pour ajouter du matériel à ce cours, vous devez suivre les recommandations dans ces annexes. Vous ne devez pas changer les conditions dans ces annexes, à l’exception de la clarification. 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

This manual is written using Sphinx, a Python document generator using the reStructuredText markup language. Instructions on how to use these tools are available on their respective sites.

19.3. Ajout d’un module

  • Pour ajouter un nouveau module, 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.

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

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

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

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

  • Ouvrez votre propre index de votre nouveau module ([module name]/index.rst).

  • Le long du haut de la page, écrivez une ligne de 80 astérisques (*). Cela représente l’en-tête d’un module.

  • Poursuivez cela avec une ligne contenant la balise |MOD| (qui signifie “module”), suivie par le nom de votre module.

  • Terminez cela avec une autre ligne de 80 astérisques.

  • Laissez une ligne ouverte sous ça.

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

  • 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 :

*******************************************************************************
|MOD| 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:

  • Ouvrez le répertoire du module.

  • Ouvrez le fichier :kbd:`index.rst (créé ci-dessus dans le cas de nouveaux modules).

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

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

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

  • Avant de rédiger la leçon, écrivez la balise |LS| suivie du nom de la leçon.

  • À la ligne suivante, écrivez une ligne de 80 signes égal (=).

  • Laissez une ligne ouverte après ceci.

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

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

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

    **The goal for this lesson:**
  • Expliquez brièvement le résultat escompté à la fin de cette leçon.

  • 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: “Suivez le fil” et “Essayez vous-même”.

  • Une section “Suivez le fil” 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 vient avec un niveau de difficulté. Une section facile est signalée par |basic|, une intermédiaire par |moderate|, et une section avancée par |hard|.

19.5.1. Ajout d’une section “Suivez le fil”

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

  • Laissez un espace puis écrivez |FA| (pour “Suivez le fil”, Follow Along en anglais).

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

  • À la ligne suivante, écrivez une ligne de 80 tirets/traits d’union (-). Assurez-vous que votre éditeur de texte ne remplace pas le caractère tirets/traits d’union avec une longue ligne ou un autre caractère.

  • É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.

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

  • 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”

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

  • Laissez un espace puis écrivez |TY| (pour “Essayez vous-même” en anglais).

  • À la ligne suivante, écrivez une ligne de 80 tirets/traits d’union (-). Assurez-vous que votre éditeur de texte ne remplace pas le caractère tirets/traits d’union avec une longue ligne ou un autre caractère.

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

  • 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 remplir la mission donnée dans cette section. Pour faire cela, vous aurez besoin d’ajouter une entrée dans la feuille de réponse.

  • Premièrement, décidez d’un nom unique pour la réponse. Idéalement, ce nom inclura le nom de la leçon et un numéro d’incrémentation.

  • Créez un lien pour cette réponse :

    :ref:`Check your results <answer-name>`
  • Ouvrez la feuille de réponses (answers/answers.rst).

  • Créez un lien vers la section “Essayez vous-même” en écrivant cette ligne:

    .. _answer-name:
  • Écrivez les instructions sur comment terminer les tâches, en utilisant des liens et des images où cela est nécessaire.

  • Pour finir, incluez un lien vers la section “Essayez vous-même” en écrivant cette ligne:

    :ref:`Back to text <backlink-answer-name>`
  • Pour que ce lien fonctionne, ajoutez la ligne suivante au-dessus de l’en-tête de la section “Essayez vous-même”:

    .. _backlink-answer-name:

Souvenez-vous que chacune de ces lignes montrées plus haut doivent avoir une ligne blanche en-dessus et en-dessous d’elles-mêmes, autrement cela pourrait causer des erreurs lors de la création du document.

19.6. Ajout d’une conclusion

  • Pour terminer une leçon, écrivez la phrase |IC| pour “in conclusion” (qui signifie “Pour conclure” en anglais), suivie par une nouvelle ligne de 80 tirets/ traits d’union (-). Écrivez une conclusion pour la leçon, expliquant quels concepts ont été abordés dans la leçon.

19.7. Ajout d’une section Pour aller plus loin

  • Cette section est optionnelle.

  • Écrivez une phrase FR pour “further reading” (qui signifie “Pour aller plus loin” en anglais), suivie par une nouvelle ligne de 80 tirets/traits d’union (-).

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

19.8. Ajout d’une section La suite ?

  • Écrivez la phrase |WN| pour “what’s next” (qui signifie “La suite ?” en anglais), suivie par une nouvelle ligne de 80 tirets/traits d’union (-).

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

  • 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 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

  • Quand vous ajoutez une image, sauvegardez-la dans le dossier _static/lesson_name/.

  • Incluez-la dans le document comme ceci

    .. image:: /static/training_manual/lesson_name/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. Using monospaced text

  • When you are writing text that the user needs to enter, a path name, or the name of a database element such as a table or column name, you must write it in monospaced text. For example:

    Enter the following path in the text box: :kbd:`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

  • You might need to a note in the text, which explains extra details that can’t easily be made part of the flow of the lesson. This is the markup:

    [Normal paragraph.]
    
    .. note:: Note text.
       New line within note.
    
       New paragraph within note.
    
    [Unindented text resumes normal paragraph.]

19.9.10. Adding a sponsorship/authorship note

If you are writing a new module, lesson or section on behalf of a sponsor, you must include a short sponsor message of their choice. This must notify the reader of the name of the sponsor and must appear below the heading of the module, lesson or section that they sponsored. However, it may not be an advertisement for their company.

If you have volunteered to write a module, lesson or section in your own capacity, and not on behalf of a sponsor, you may include an authorship note below the heading of the module, lesson or section that you authored. This must take the form This [module/lesson/section] contributed by [author name]. Do not add further text, contact details, etc. Such details are to be added in the “Contributors” section of the Foreword, along with the name(s) of the part(s) you added. If you only made enhancements, corrections and/or additions, list yourself as an editor.

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.