Important

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

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.

Sections used to structure the text are identified through their title which is underlined (and overlined for the first level). Same level titles must use same character for underline adornment. Precede section titles with a blank line. In QGIS Documentation, you should use following styles for chapter, section, subsection and minisec.

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

Indentation in reStructuredText should be aligned with the list or markup marker. It is also possible to create block quotes with indentation. See the Specification

#. 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.4. Balises en ligne

Vous pouvez utiliser des balises pour souligner les éléments.

  • Interface de menu : pour indiquer une séquence de sélections dans un menu, y compris la sélection de sous-menus et le choix d’une opération particulière, ou n’importe quelle sous-séquence d’une telle séquence.

    :menuselection:`menu --> submenu`

  • Boîtes de dialogue et titres d’onglet: étiquettes présentées dans le cadre d’une interface utilisateur interactive, y compris les titres de fenêtre, les titres d’onglet, les étiquettes de bouton et d’option.

    :guilabel:`title`

  • Noms de fichiers et répertoires

    :file:`README.rst`

  • Icônes avec texte contextuel

    |icon| :sup:`popup_text`

    (voir image ci-dessous).

  • Raccourcis clavier

    :kbd:`Ctrl+B`

    affichera Ctrl+B

    Lors de la description des raccourcis clavier, les conventions suivantes doivent être utilisées:

    • Les lettres sont affichées en majuscules: S

    • Les touches spéciales sont affichées avec une première lettre majuscule: Esc

    • Les combinaisons de touches sont affichées avec un signe + entre les touches, sans espaces: Shift+R

  • Texte utilisateur

    ``label``

  • Layers, databases, tables or columns names

    When referring to layers, databases, tables or columns, format as inline code:

    ``layer name``
``database_name``
``table_name``
``column_name``

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

../../_images/logo.png

Icon substitution

You can add an image inside a text paragraph (e.g., as a tool icon). To do so, you first need to create an alias (also named substitution), which is a reference name used to display the icon. To ensure consistency across the documents and help in the use of the icons, we maintain a list in the substitutions.txt file at the root of this repository. Find more details in the Substitutions chapter.

Using an icon substitution is usually achieved through these steps:

  1. Add the icon substitution in the substitutions.txt file as below. If a substitution already exists for the icon you want to use, then skip this step.

    .. |logo| image:: /static/common/logo.png
   :width: 1 em

  2. Call it in your paragraph:

    My paragraph begins here with |logo|.

  3. Add (again) the icon substitution at the end of the file you are modifying. This helps connecting the replacement text with the actual image, and can be done by copy-pasting it from substitutions.txt or by executing the scripts/find_set_subst.py script.

    Voici comment l’exemple sera affiché:

    My paragraph begins here with logo.

Figure

.. _figure_logo:

.. figure:: /static/common/logo.png
   :width: 20 em
   :align: center

   A caption: A logo I like

Le résultat ressemble à cela :

../../_images/logo.png

Fig. 2.24 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.24

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 :

voir Un titre : Un logo que j’aime

2.1.7. Tables

You can make a simple table like this:

=======  =======  =======
x        y        z
=======  =======  =======
1        2        3
4                 5
=======  =======  =======

Il sera rendu ainsi :

x

y

z

1

2

3

4

5

Tables should have a caption. You can use an explicit reST « table » directive to add a caption to simple tables or grid tables. Add the caption on the same line as the directive and indent the table at least one space.

You can also add a hyperlink target before a table in order to reference it elsewhere. To avoid conflicts with other references, always begin hyperlink targets with _table_ and use terms relevant to the table caption.

Here is an example of a more complicated grid table with a caption and a hyperlink target:

.. _table-grid-caption:

.. table:: Grid table with caption

   +---------------+--------------------+
   | Windows       | macOS              |
   +---------------+--------------------+
   | |win|         | |osx|              |
   +---------------+--------------------+
   | and of course not to forget |nix|  |
   +------------------------------------+

Le résultat :

Tableau 2.2 Grid table with caption

Windows

macOS

win

osx

et bien sûr, ne pas oublier nix

You may find it easier to use list tables or CSV tables to make complex tables. Add the caption after the list-table or csv-table directive.

Here is an example of a list table with a caption and a hyperlink target:

.. _table-list-caption:

.. list-table:: List table with caption
   :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 :

Tableau 2.3 List table with caption

Quoi

Fonction

Mot-clé

Description

Test

Test utile

complexité

Géométrie. Un des:

  • Point

  • Ligne

Use :numref: roles to reference tables like this:

see :numref:`table-grid-caption` or :numref:`table-list-caption`

Le résultat :

Note

You must add a caption to your table in order to create a cross reference with the :numref: role.

2.1.8. 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-à-dire Chargement des couches au lieu de chargement_couches ou chargementCouches.

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

Several index tags exist in reST. You can use the inline :index: tag within normal text:

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.9. 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.10. 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

Text in special comments will be translated, but text in code-block frames will not be translated. So keep comments in code blocks as short as possible and avoid comments unrelated to code.

2.1.11. Notes de pied de page

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.

  • You can find some prepared QGIS projects that are used to create screenshots in the ./qgis-projects folder of this repository. This makes it easier to reproduce screenshots for the next version of QGIS. These projects use the QGIS Sample Data (aka Alaska Dataset), which should be unzipped and placed in the same folder as the QGIS-Documentation Repository.

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

  • Set print size resolution to 135 dpi (e.g., in GIMP scale down the image using Image ► Scale Image and setting « X/Y » to 135 pixels/in, and export it through File ► Export…). This way, images will be at original size in HTML and at a good print resolution in the PDF.

    Vous pouvez également utiliser la commande convert de ImageMagick sur 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:

Translated images should be placed in a img/<your_language>/ folder. Use the same filename as the “original” English screenshot.

2.3. Documenter les algorithmes de traitement

Si vous souhaitez écrire de la documentation sur les algorithmes de traitement, tenez compte des recommandations suivantes:

  • Processing algorithm help files are part of QGIS User Guide, so use the same formatting as the User Guide and other 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.

  • It is extremely important that each algorithm has an anchor that corresponds to the provider name + the unique name of the algorithm itself. This allows the Help button to open the Help page of the correct section. The anchor should be placed above the title, e.g. (see also the Étiquettes / références section):

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

  • Avoid using « This algorithm does this and that… » as the first sentence in the algorithm description. Try to use more general expressions like:

    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 la couche d'entrée comme une couche à 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 .png et 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 dossier img à côté du fichier .rst que 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.

  • Add the default value of the parameter, e.g.:

    * - **Number of points**
  - ``NUMBER_OF_POINTS``
  - [numeric: integer]

    Default: 1
  - Number of points to create

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

    pointLayer

    Couche vecteur de lignes

    vecteur : ligne

    lineLayer

    Couche vectorielle polygone

    vecteur : polygone

    polygonLayer

    Toutes couches vectorielles spatiales

    vecteur: géométrie

    Couche vectorielle non géométrique

    vecteur : table

    tableLayer

    Couche vectorielle générique

    vector: any

    Champ vecteur numérique

    tablefield: numeric

    fieldFloat

    Champ vecteur texte

    tablefield: string

    fieldText

    Champ générique de vecteur

    tablefield: any

    Couche raster

    raster

    rasterLayer

    Bande raster

    raster band

    Fichier HTML

    html

    Expression

    expression

    expression

    Line geometry

    geometry: line

    Géométrie de point

    coordinates

    Etendue

    extent

    SCR

    crs

    setProjection

    Enumeration

    enumeration

    selectString

    Liste

    liste

    Valeur de type entier

    numérique : entier

    selectNumber

    Valeur décimale

    numérique: décimal

    selectNumber

    Caractère

    string

    inputText

    Booléen

    boolean

    checkbox

    Chemin d’accès au dossier

    folder

    Fichier

    file

    Table

    matrix

    Couche

    layer

    Même type de sortie que le type d’entrée

    same as input

    Definition

    definition

    Couches cartographiques

    couche liste

    Portée

    range

    AuthConfig

    authconfig

    Maillage

    mesh

    Mise en page

    layout

    Element mise en page

    layoutitem

    Couleur

    color

    Échelle

    scale

    Thème de carte

    thème de carte

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

Here is an example of an existing algorithm to help you with the layout and the 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
   :class: longtable

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