Important
La traduction est le fruit d’un effort communautaire auquel vous pouvez vous joindre. Cette page est actuellement traduite à 100.00%.
2. Recommandations pour rédiger
En général, lors de la création de la documentation reST pour le projet QGIS, veuillez suivre les Consignes de style de documentation Python. Pour plus de commodité, nous fournissons ci-dessous un ensemble de règles générales sur lesquelles nous nous appuyons pour rédiger la documentation QGIS.
2.1. Rédiger la Documentation
2.1.1. Titres
À chaque page web de la documentation correspond un fichier .rst.
Les différentes parties qui structurent le texte sont identifiées par leur titre qui est souligné (et surligné pour le premier niveau). Les titres de même niveau doivent utiliser le même caractère de soulignement. Dans la documentation QGIS, voici les styles à utiliser pour le chapitre, la section, la sous-section et la mini section.
********
Chapter
********
Section
=======
Subsection
----------
Minisec
.......
Subminisec
^^^^^^^^^^
2.1.2. Listes
Les listes sont utiles pour structurer le texte. Voici quelques règles simples communes à toutes les listes :
Commencez tous les éléments de la liste avec une majuscule
N’utilisez pas de ponctuation après les éléments de liste qui ne contiennent qu’une seule phrase simple
Utilisez le point (
.) comme signe de ponctuation pour les éléments de liste qui se composent de plusieurs phrases ou d’une seule phrase composée
2.1.3. Indentation
Dans le langage RestructuredText, l’indentation est primordiale. Dans les listes, les textes comme les symboles doivent être alignées. On peut également créer des zones de citation en jouant avec le décalage de texte. Lire les Spécifications
#. In a numbered list, there should be
three spaces when you break lines
#. And next items directly follow
* Nested lists
* Are also possible
* And when they also have
a line that is too long,
the text should be naturally
aligned
* and be in their own paragraph
However, if there is an unindented paragraph, this will reset the numbering:
#. This item starts at 1 again
2.1.5. Étiquettes / références
Les ancres à l’intérieur du texte peuvent être utilisées pour créer des hyperliens vers des sections ou des pages.
L’exemple ci-dessous crée la référence d’une section (e.g., Libellé/titre de la référence)
.. _my_anchor:
Label/reference
---------------
Pour appeler la référence dans la même page, utilisez
see my_anchor_ for more information.
qui renverra :
voir my_anchor pour plus d’informations.
Notez qu’il sautera à la ligne / chose qui suit «l’ancre». Vous n’avez pas besoin d’utiliser des apostrophes, mais vous devez avoir des lignes vides après l’ancre.
Une autre façon de créer un lien accessible depuis n’importe où dans la documentation est d’utiliser :ref:.
see :ref:`my_anchor` for more information.
ce qui créera un lien avec la légende à la place (dans ce cas le titre de cette section!):
voir Étiquettes / références pour plus d’informations.
Donc, référence 1 (my_anchor) et référence 2 (Étiquettes / références). Étant donné que la référence affiche souvent une légende complète, il n’est pas vraiment nécessaire d’utiliser le mot section. Notez que vous pouvez également utiliser une légende personnalisée pour décrire la référence:
see :ref:`Label and reference <my_anchor>` for more information.
qui renvoie:
voir Étiquette et référence pour davantage de détails.
2.1.6. Figures et images
Illustrations
Pour insérer une image, utilisez
.. figure:: /static/common/logo.png
:width: 10 em
qui renvoie
Remplacement
Vous pouvez mettre une image dans du texte ou ajouter un alias à utiliser partout. Pour utiliser une image à l’intérieur d’un paragraphe, créez d’abord un alias dans le fichier source/substitutions.txt:
.. |nice_logo| image:: /static/common/logo.png
:width: 1 em
puis appelez-le dans votre paragraphe:
My paragraph begins here with a nice logo |nice_logo|.
Voici comment l’exemple sera affiché:
Mon paragraphe commence ici par un joli logo .
Pour permettre un aperçu de rendu dans GitHub aussi proche que possible du rendu HTML, vous devrez également ajouter l’appel de remplacement d’image à la fin du fichier que vous avez modifié. Cela peut être fait en le copiant-collant depuis substitutions.txt ou en exécutant le script scripts/find_set_subst.py.
Note
Actuellement, pour assurer la cohérence et aider à l’utilisation des icônes QGIS, une liste d’alias est construite et disponible dans le chapitre Substitutions.
Figure
.. _figure_logo:
.. figure:: /static/common/logo.png
:width: 20 em
:align: center
A caption: A logo I like
Le résultat ressemble à cela :
Fig. 2.23 Un titre : Un logo que j’aime
Pour éviter les conflits avec d’autres références, commencez toujours les ancres de figures par _figure_ et utilisez des termes qui se connectent facilement à la légende de la figure. Bien que seul l’alignement centré soit obligatoire pour l’image, n’hésitez pas à utiliser d’autres options pour les figures (telles que width, height, scale …) si nécessaire.
Les scripts inséreront un numéro généré automatiquement avant la légende du chiffre dans les versions HTML et PDF de la documentation générée.
Pour utiliser un titre (voir Mon titre) insérez juste un texte indenté après une ligne blanche dans le bloc de la figure.
Une figure peut être référencée à l’aide de l’étiquette de référence comme ceci:
see :numref:`figure_logo`
rend comme ceci :
voir Fig. 2.23
C’est la façon préférée de référencer les nombres.
Note
Pour que :numref: fonctionne, le chiffre doit avoir une légende.
Il est possible d’utiliser :ref: au lieu de :numref: pour ajouter des références, mais celui-ci renvoie le label complet de l’image.
see :ref:`figure_logo`
rend comme ceci :
Tables
Un simple tableau peut être codé comme suit
======= ======= =======
x y z
======= ======= =======
1 2 3
4 5
======= ======= =======
Il sera rendu ainsi :
x |
y |
z |
|---|---|---|
1 |
2 |
3 |
4 |
5 |
Utilisez une barre oblique inversée (backslash) suivie d’un espace vide pour laisser un espace vide.
Vous pouvez également faire des tableaux plus compliqués et les référencer :
.. _my_drawn_table:
+---------------+--------------------+
| Windows | macOS |
+---------------+--------------------+
| |win| | |osx| |
+---------------+--------------------+
| and of course not to forget |nix| |
+------------------------------------+
My drawn table, mind you this is unfortunately not regarded as a caption
You can reference it like this: my_drawn_table_.
Le résultat :
Windows |
macOS |
|
|
et bien sûr, ne pas oublier |
|
Ma table dessinée, remarquez que ce n’est malheureusement pas considéré comme une légende
Vous pouvez le référencer comme ceci my_drawn_table.
Pour des tables encore plus complexes, il est plus simple d’utiliser list-table:
.. list-table::
:header-rows: 1
:widths: 20 20 20 40
* - What
- Purpose
- Key word
- Description
* - **Test**
- ``Useful test``
- complexity
- Geometry. One of:
* Point
* Line
Le résultat :
Quoi |
Fonction |
Mot-clé |
Description |
|---|---|---|---|
Test |
|
complexité |
Géométrie. Un des:
|
2.1.7. Index
Un index est un moyen pratique pour aider le lecteur à trouver des informations dans un document. La documentation QGIS fournit quelques indices essentiels. Il existe quelques règles qui nous aident à fournir un ensemble d’indices vraiment utiles (cohérents, consistant et vraiment connectés les uns aux autres):
Un index doit être lisible par l’homme, compréhensible et traduisible; un index peut être créé à partir de nombreux mots, mais vous devez éviter tout caractère inutile
_, ``-… pour les lier, c’est-à-direChargement des couchesau lieu dechargement_couchesouchargementCouches.Ne mettez en majuscule que la première lettre de l’index, sauf si le mot a une orthographe particulière. Par exemple,
Chargement des couches,Génération Atlas,WMS,pgsql2shp.Gardez un œil sur la Liste d’index existante afin de réutiliser l’expression la plus pratique avec l’orthographe correcte et d’éviter les doublons inutiles.
Plusieurs balises d’index existent dans RST. Vous pouvez utiliser la balise inline :index: dans le texte normal:
QGIS can load several :index:`Vector formats` supported by GDAL ...
Ou vous pouvez utiliser le balisage de niveau bloc .. index:: qui renvoie au début du paragraphe suivant. En raison des règles mentionnées ci-dessus, il est recommandé d’utiliser la balise de niveau bloc:
.. index:: WMS, WFS, Loading layers
Il est également recommandé d’utiliser des paramètres d’index tels que single, pair et see, afin de construire une table d’index plus structurée et interconnectée. Voir Génération d’index pour plus d’informations sur la création d’index.
2.1.8. Commentaires Spéciaux
Parfois, vous souhaiterez peut-être mettre l’accent sur certains points de la description, soit pour avertir, rappeler ou donner des conseils à l’utilisateur. Dans la documentation QGIS, nous utilisons des directives spéciales reST telles que .. warning::, .. seealso::, .. note::`` et .. tip::. Ces directives génèrent des cadres qui mettent en valeur vos commentaires. Voir Balisage de niveau de paragraphe pour plus d’informations. Un titre clair et approprié est requis pour les avertissements et les conseils.
.. tip:: **Always use a meaningful title for tips**
Begin tips with a title that summarizes what it is about. This helps
users to quickly overview the message you want to give them, and
decide on its relevance.
2.1.9. Extraits de code
Vous pouvez également donner des exemples et insérer des extraits de code. Dans ce cas, écrivez le commentaire sous une ligne avec la directive :: insérée. Pour un meilleur rendu, en particulier pour appliquer une surbrillance des couleurs au code en fonction de son langage, utilisez la directive de bloc de code, par ex. .. code-block:: xml. Plus de détails sur Affichage du code.
Note
Bien que les textes des cadres de notes, de conseils et d’avertissement soient traduisibles, sachez que les cadres de blocs de code ne permettent pas la traduction. Évitez donc les commentaires non liés au code et gardez les commentaires aussi courts que possible.
2.1.10. Notes de pied de page
Remarque: Les notes de bas de page ne sont reconnues par aucun logiciel de traduction et elles ne sont pas non plus correctement converties au format PDF. Donc, si possible, n’utilisez pas de notes de bas de page dans la documentation.
Pour créer une note de bas de page (montrant comme exemple [1])
blabla [1]_
qui pointera vers :
2.2. Les Captures d’écrans
2.2.1. Ajouter de nouvelles captures d’écran
Voici quelques conseils pour créer de nouvelles captures d’écran attrayantes. Les images doivent être placées dans un dossier image (img/) qui se trouve dans le même dossier que le fichier de référence .rst.
Vous pouvez trouver des projets QGIS préparés qui sont utilisés pour créer des captures d’écran dans le dossier
./Qgis-projectsde ce référentiel. Cela facilite la reproduction de captures d’écran pour la prochaine version de QGIS. Ces projets utilisent des données du dépôt QGIS-Sample-Data (alias jeu de données Alaska), qui doit être placé dans le même dossier que le dépôt de la documentation QGIS.Réduisez la fenêtre à l’espace minimal nécessaire pour afficher la fonctionnalité (prendre tout l’écran pour une petite fenêtre modale est exagéré)
Moins d’encombrement, mieux c’est (pas besoin d’activer toutes les barres d’outils)
Ne les redimensionnez pas dans un éditeur d’images; la taille sera définie dans les fichiers
.rstsi nécessaire (réduction des dimensions sans augmenter correctement la résolution)Coupez l’arrière-plan
Rendez les coins supérieurs transparents si l’arrière-plan n’est pas blanc
Réglez la résolution de la taille d’impression sur
135 dpi(par exemple, dans Gimp, définissez la résolution d’impression et enregistrez). De cette façon, les images seront à leur taille d’origine en html et à une bonne résolution d’impression dans le PDF. Vous pouvez également utiliser la commande ImageMagick convert pour faire un lot d’images:convert -units PixelsPerInch input.png -density 135 output.png
Enregistrez-les sous
.png(pour éviter les artefacts.jpeg)La capture d’écran doit montrer le contenu selon ce qui est décrit dans le texte
Astuce
Si vous utilisez Ubuntu, vous pouvez utiliser la commande suivante pour supprimer la fonction de menu global et créer des écrans d’application plus petits avec des menus:
sudo apt autoremove appmenu-gtk appmenu-gtk3 appmenu-qt
2.2.2. Captures d’écran traduites
Voici quelques conseils supplémentaires pour ceux qui souhaitent créer des captures d’écran pour un guide d’utilisateur traduit:
Les images traduites doivent être placées dans un dossier img/<your_language>/. Utilisez le même nom de fichier que la capture d’écran «originale» en anglais.
2.3. Documenter les algorithmes de traitement
Si vous souhaitez écrire de la documentation sur les algorithmes de traitement, tenez compte des recommandations suivantes:
Les fichiers d’aide de l’algorithme de traitement font partie du Guide de l’utilisateur de QGIS, utilisez donc le même formatage que le Guide de l’utilisateur et toute autre documentation.
Chaque documentation d’algorithme doit être placée dans le dossier provider et le fichier group correspondants, par ex. l’algorithme Voronoi polygon appartient au fournisseur QGIS et au groupe vectorgeometry. Le fichier correct pour ajouter la description est donc:
source/docs/user_manual/processing_algs/qgis/vectorgeometry.rst.Note
Avant de commencer à rédiger le guide, vérifiez si l’algorithme est déjà décrit. Dans ce cas, vous pouvez améliorer la description existante.
Il est extrêmement important que chaque algorithme ait une ancre qui correspond au nom du fournisseur + le nom unique de l’algorithme lui-même. Cela permet au bouton Aide d’ouvrir la page d’aide de la bonne section. L’ancre doit être placée au-dessus du titre, par ex. (voir aussi la section Étiquettes / références)
.. _qgisvoronoipolygons: Voronoi polygons ----------------
Pour connaître le nom de l’algorithme, vous pouvez simplement passer la souris sur l’algorithme dans la boîte à outils Traitement.
Évitez d’utiliser « Cet algorithme fait ceci et cela … » comme première phrase de la description de l’algorithme. Essayez d’utiliser des expressions plus générales comme
Takes a point layer and generates a polygon layer containing the...
Évitez de décrire ce que fait l’algorithme en répliquant son nom et veuillez ne pas répliquer le nom du paramètre dans la description du paramètre lui-même. Par exemple, si l’algorithme est un
polygone de Voronoï, envisagez de décrire lacouche d'entréecomme unecouche à partir de laquelle calculer le polygone.Indiquez dans la description si l’algorithme a un raccourci par défaut dans QGIS ou prend en charge l’édition sur place.
Ajoutez des images ! Une image vaut mieux que mille mots ! Utilisez le format
.pnget suivez les instructions générales pour la documentation (voir la section Figures et images pour plus d’informations). Placez le fichier image dans le dossier correct, c’est-à-dire le dossierimgà côté du fichier.rstque vous modifiez.Si nécessaire, ajoutez des liens dans la section « Voir aussi » qui fournissent des informations supplémentaires sur l’algorithme (par exemple, des publications ou des pages Web). N’ajoutez la section « Voir aussi » que s’il y a vraiment quelque chose à voir. Comme bonne pratique, la section « Voir aussi » peut être remplie de liens vers des algorithmes similaires.
Expliquez clairement les paramètres et les sorties des algorithmes: inspirez-vous des algorithmes existants.
Évitez de dupliquer la description détaillée des options de l’algorithme. Ajoutez ces informations dans la description du paramètre.
Évitez d’ajouter des informations sur le type de géométrie vectorielle dans l’algorithme ou la description des paramètres, car ces informations sont déjà disponibles dans les descriptions des paramètres.
Ajoutez la valeur par défaut du paramètre, par exemple:
* - **Number of points** - ``NUMBER_OF_POINTS`` - [number] Default: 1 - Number of points to createDécrivez le type d’entrée pris en charge par les paramètres. Il existe plusieurs types disponibles, vous pouvez en choisir un:
Paramètre/type de sortie
Description
Indicateur visuel
Couche vecteur de points
vecteur : point
Couche vecteur de lignes
vecteur : ligne
Couche vectorielle polygone
vecteur : polygone
Couche vectorielle générique
vector: anyChamp vecteur numérique
tablefield: numeric
Champ vecteur texte
tablefield: string
Champ générique de vecteur
tablefield: anyCouche raster
raster
Bande raster
raster bandFichier HTML
htmlCouche de table
table
Expression
expression
Géométrie de point
coordinatesEtendue
extentSCR
crs
Enumeration
enumeration
Liste
listeNombre
number
Caractère
string
Booléen
booléen
Chemin d’accès au dossier
folderFichier
fileTable
matrixCouche
layerMême type de sortie que le type d’entrée
same as inputDefinition
definitionPoint
pointMultipleLayers
multipleLayersPlage
rangeAuthConfig
authconfigMaillage
meshMise en page
layoutElement mise en page
layoutitemCouleur
colorÉchelle
scaleÉtudiez un algorithme existant et bien documenté, et copiez toutes les dispositions utiles.
Lorsque vous avez terminé, suivez simplement les instructions décrites dans Contribuer étape par étape pour valider vos modifications et effectuer une requete d’amelioration
Voici l’exemple d’un algorithme pour vous aider dans la mise en forme et la description
.. _qgiscountpointsinpolygon:
Count points in polygon
-----------------------
Takes a point and a polygon layer and counts the number of points from the
point layer in each of the polygons of the polygon layer.
A new polygon layer is generated, with the exact same content as the input
polygon layer, but containing an additional field with the points count
corresponding to each polygon.
.. figure:: img/count_points_polygon.png
:align: center
The labels in the polygons show the point count
An optional weight field can be used to assign weights to each point.
Alternatively, a unique class field can be specified. If both options
are used, the weight field will take precedence and the unique class field
will be ignored.
``Default menu``: :menuselection:`Vector --> Analysis Tools`
Parameters
..........
.. list-table::
:header-rows: 1
:widths: 20 20 20 40
* - Label
- Name
- Type
- Description
* - **Polygons**
- ``POLYGONS``
- [vector: polygon]
- Polygon layer whose features are associated with the count of
points they contain
* - **Points**
- ``POINTS``
- [vector: point]
- Point layer with features to count
* - **Weight field**
Optional
- ``WEIGHT``
- [tablefield: numeric]
- A field from the point layer.
The count generated will be the sum of the weight field of the
points contained by the polygon.
* - **Class field**
Optional
- ``CLASSFIELD``
- [tablefield: any]
- Points are classified based on the selected attribute and if
several points with the same attribute value are within the
polygon, only one of them is counted.
The final count of the points in a polygon is, therefore, the
count of different classes that are found in it.
* - **Count field name**
- ``FIELD``
- [string]
Default: 'NUMPOINTS'
- The name of the field to store the count of points
* - **Count**
- ``OUTPUT``
- [vector: polygon]
Default: [Create temporary layer]
- Specification of the output layer type (temporary, file,
GeoPackage or PostGIS table).
Encoding can also be specified.
Outputs
.......
.. list-table::
:header-rows: 1
:widths: 20 20 20 40
* - Label
- Name
- Type
- Description
* - **Count**
- ``OUTPUT``
- [vector: polygon]
- Resulting layer with the attribute table containing the
new column with the points count