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
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, 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).
En 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 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 comprenant 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: « Etape 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 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 « Etape par étape »
Pour commencer cette section, écrivez la balise du niveau de difficulté prévu (comme montré ci-dessus).
Laissez un espace puis écrivez |FA| (pour « Pas à pas », 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
.. 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.4. Liens internes
Pour créer un point d’ancrage pour un lien, écrivez la ligne suivante au-dessus de l’endroit où vous souhaitez que le lien pointe
.. _link-name:
Pour créer un lien, ajoutez cette ligne:
:ref:`Descriptive link text <link-name>`
Rappelez-vous de laisser une ligne vide avant et après cette ligne.
19.9.5. Liens externes
Pour créer un lien externe, écrivez-le comme ceci:
`Descriptive link text <link-url>`_
Rappelez-vous de laisser une ligne vide avant et après cette ligne.
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: :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
Vous devriez rédiger une note dans le texte qui donne plus de détails qui ne peuvent faire partie du flux 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.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.