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

Recommandations pour la documentation

Introduction

La documentation QGIS va être créée automatiquement sur le serveur à 0h, 8h, 16h PDT (Heure du Pacifique) ou UTC-8. Le statut actuel est disponible à cette adresse http://docs.qgis.org.

La documentation de QGIS est principalement écrite en utilisant la syntaxe du format reStructuredText (reST), associée avec quelques scripts de la boîte à outils Sphinx pour le post traitement de la sortie HTML. Voir http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html or http://sphinx.pocoo.org/markup/inline.html.

D’une manière générale, quand vous produisez de la documentation reST pour le projet QGIS, merci de vous conformer au document Python documentation style guidelines. Quelques directives générales pour l’utilisation de reST dans le cadre de l’écriture de documentation pour QGIS sont exposées ci dessous.

Si vous cherchez des recomandations générales pour contribuer au projet QGIS ou gérer des dépôts, vous pouvez trouver de l’aide en vous rendant sur S’impliquer dans la communauté QGIS.

Rédiger la Documentation

Titres de chapitre

À 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
^^^^^^^^^^

Balises en ligne

Quelques balises peuvent être utilisées dans le texte pour mettre en valeur certains é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`
  • Titre de boite de dialogue et d’onglet: Libellés faisant partie d’une boite de dialogue interactive y compris le titre de la fenêtre, le titre des onglets et le libellé des options.

    :guilabel:`title`
  • Libellé de bouton

    **[Apply]**
  • Nom de fichier ou de répertoire

    :file:`README.rst`
  • Icone et texte du popup de l’icone

    |icon| :sup:`popup_text`

    (voir image ci-dessous).

  • Raccourcis clavier

    :kbd:`ctrl B`

    affichera Ctrl B

  • Texte utilisateur

    ``label``
    

Étiquette/référence

Les références servent de repères dans le texte. Cela facilite la création et l’utilisation d’hyperliens entre les sections ou les 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.

Remarquez que le lien vous amènera à l’élément situé immédiatement après ‘l’ancre’. Normalement, pour déclarer cette référence, il n’est pas nécessaire d’utiliser des apostrophes mais il faut une ligne vide avant et 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.

qui affichera la légende à la place (dans ce cas le titre de la section!):

voir Étiquette/référence pour plus d’informations.

On a donc référence 1 (my_anchor) et référence 2 (Étiquette/référence). Parce que la référence affiche souvent une description complète, il n’est pas vraiment utile d’utiliser le mot section. Notez que vous pouvez aussi utiliser une description personnalisée pour la référence

see :ref:`Label and reference <my_anchor>` for more information.

renvoyant :

voir Label and reference pour d’avantage de détails.

Figure et image

Illustrations

Pour insérer une image, utilisez

.. image:: /static/common/qgislogo.png
   :width: 10 em

qui renvoie

../../_images/qgislogo.png

Remplacement

Vous pouvez placer une image dans un texte ou ajouter un alias pour l’utiliser régulièrement. Pour utiliser une image dans un paragraphe, créez juste un alias quelque part.

.. |nice_logo| image:: /static/common/qgislogo.png
               :width: 2 em

et l’appeler dans votre paragraphe :

my paragraph begins here with a nice logo |nice_logo|.

Voici comment l’exemple apparaît :

mon paragraphe commence ici avec un beau logo nice_logo.

Note

Actuellement, pour garantir la cohérence et faciliter l’utilisation des icones de QGIS, une liste d’alias a été constituée et est disponible dans le chapitre ref:substitutions.

Figure

.. _figure_readme_1:

.. only:: html

   **Figure Readme 1:**

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

   A caption: A logo I like

Le résultat ressemble à ceci :

Figure Readme 1:

../../_images/qgislogo.png

Un titre : Un logo que j’aime

Utilisez .. only:: html pour rendre le numéro de la figure (Figure Readme 1) visible seulement dans les fichiers html. Les scripts inséreront un numéro généré automatiquement avant le titre de la figure dans le document pdf.

Pour utiliser un titre (voir Mon titre) insérez juste un texte indenté après une ligne blanche dans le bloc de la figure.

La référence à la figure peut être faite en utilisant l’étiquette de la référence comme ceci :

(see Figure_Readme_1_).

Cela affichera l’ancre Figure_Readme_1. Vous pouvez mettre en majuscule si vous le désirez. Il doit être utilisé dans le même fichier .rst pas dans un autre.

Vous ne pouvez plus utiliser :ref:, parce qu’en html la référence à la description est perdue (le lien pointe vers l’endroit immédiatement avant Figure Readme 1:)

see :ref:`figure_readme_1`, does not work due to the lost reference to
the caption of the figure, this is not a 'bug' but a choice we made!

Tables

Pour créer une table simple

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

Utilisez un \ suivi par un espace vide pour laisser un espace vide.

Vous pouvez aussi utiliser des tableaux plus compliqués en les dessinant avec des références etc.

.. _my_drawn_table_1:

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

My drawn table, mind you this is unfortunately not regarded a caption

You can reference to it like this my_drawn_table_1_.

Le résultat :

Windows Mac OSX
win osx

et bien sûr, ne pas oublier nix

Mon tableau établi, voyez-vous ce n’est malheureusement pas considéré comme une légende

Vous pouvez le référencer comme ceci my_drawn_table_1.

Index

Il existe différents tags d’index dans le format RST. Pour pouvoir traduire l’index, il est nécessaire de l’intégrer dans le texte normal. Dans ce cas, utilisez cette syntaxe :

QGIS allows to load several :index:`Vector formats` supported by GDAL/OGR ...

Si le terme n’a pas besoin d’être traduit, veuillez utiliser cette syntaxe :

.. index:: WMS, WFS, WCS, CAT, SFS, GML, ...

Notes de pied de page

Attention : les notes de pied de page ne sont pas reconnues par les logiciels de traduction et ne sont pas converties correctement dans le format PDF. Donc, si possible, n’utilisez pas les notes de pied de page dans une documentation.

Ceci est pour créer une note de pied de page

blabla [1]_

qui pointera vers :

[1]

Mise à jour des extensions principales

Gérer les captures d’écran

Ajouter de nouvelles captures d’écran

Voici quelques conseils pour créer de nouvelles captures d’écran harmonieuses. Celles du guide utilisateur sont situées dans ./resources/en/user_manual/

  • le même environnement pour toutes les captures d’écran (même OS, même thème, même police). Nous avons utilisé Ubuntu avec Unity et le thème “ambiance” par défaut. Pour les captures d’écran de la fenêtre principale de QGIS et le composeur d’impression nous l’avons paramétré pour afficher les menus dans la fenêtre (ce n’est pas la configuration par défaut dans unity).

  • réduire la fenêtre à l’espace minimal requis pour montrer la fonction (prendre l’écran en entier pour montrer une petite fenêtre modale est excessif)

  • Moins il y a d’encombrement, mieux c’est (pas besoin d’activer toutes les barres d’outils)

  • Ne les redimensionnez pas dans un éditeur d’image, si nécessaire la taille sera définie dans les fichiers rst (réduire les dimensions sans augmenter correctement la résolution dégrade fortement l’image)

  • coupez l’arrière-plan

  • Réglez la résolution d’impression sur 135 dpi, eg dans Gimp réglez la résolution d’impression (image > taille de l’impression) et sauvegardez. De cette façon, si aucune taille n’est définie dans les fichiers rst,les images seront à leur taille d’origine en html et à une bonne résolution d’impression en PDF. Vous pouvez utiliser ImageMagick et sa commande conversion pour traiter des images en masse:

convert -units PixelsPerInch input.png -density 135 output.png
  • Enregistrez-les au format png (sans artefacts jpeg)

  • la capture d’écran doit montrer le contenu en fonction de ce qui est décrit dans le texte

  • Vous pouvez trouvez des projets QGIS tout faits qui ont été utilisés avant la création des captures d’écran dans ./qgis-projects. Cela permettra de rendre plus facile la reproduction des captures d’écran pour la prochaine version de QGIS. Ces projets utilisent le jeu de données d’exemple de QGIS Sample Data (aka Alaska Dataset) qui devrait être stocké dans le même répertoire que le dépôt de la documentation QGIS.

  • Utilisez la commande suivante pour supprimer la fonction de menu global sous Ubuntu pour créer des écrans d’application plus petits avec leurs menus :

sudo apt-get autoremove appmenu-gtk appmenu-gtk3 appmenu-qt

Traduire les captures d’écran

Voici quelques astuces pour créer des captures d’écran à destination de la traduction du guide de l’utilisateur. Elles seront situées dans ./resources/<votre langue>/user_manual/

  • même environnement pour toutes les captures d’écran (même système d’exploitation, même cadrage, même taille de police)

  • Utilisez les projets QGIS inclus dans le dépôt de la documentation QGIS (dans ./qgis_projects ). Ils ont été utilisés pour produire les captures d’écran ‘originelles’ du manuel. Le jeu de données QGIS exemple Sample Data (aka Alaska Dataset) devrait être situé dans le même répertoire que le dépôt de la documentation QGIS.

  • même taille que les captures d’écran ‘originales’ en anglais, sinon elles seront étirées et laides. Si vous avez besoin d’avoir une taille différente en raison des chaînes d’interface utilisateur, n’oubliez pas de changer la dimension dans le code rst de votre langue.

  • réduire la fenêtre à l’espace minimal requis pour montrer la fonction (prendre l’écran en entier pour montrer une petite fenêtre modale est excessif)

  • Moins il y a d’encombrement, mieux c’est (pas besoin d’activer toutes les barres d’outils)

  • Ne les redimensionnez pas dans un éditeur d’image, la taille sera définie dans les fichiers rst (réduire les dimensions sans augmenter correctement la résolution est laid)

  • coupez l’arrière-plan

  • Enregistrez-les au format png (sans artefacts jpeg)

  • la capture d’écran doit montrer le contenu en fonction de ce qui est décrit dans le texte

Documenter les algorithmes de traitement

Si vous désirez écrire de la documentation pour des algorithmes de Traitement, merci de suivre ces recommandations :

  • n’écrasez pas les fichiers d’aide déjà existants par des fichiers d’autre provenance (ex : l’arbre des sources QGIS ou le dépôt d’aide des Géotraitements), ces fichiers ont des formats différents

  • Les fichiers d’aide des algorithmes de géotraitement font partie du Guide Utilisateur de QGIS. Utilisez le même format que ce guide et des autres documentations

  • Évitez d’utiliser la phrase “Cet algorithme fait ci et ça...” comme phrase d’introduction de la description de l’algorithme. Essayez d’utiliser des mots plus génériques comme ceux de l’aide des algorithmes GRASS ou TauDEM

  • Ajoutez des images si nécessaire. Utilisez le format PNG et suivez les recommandations générales sur la documentation.

  • Si nécessaire, ajoutez des liens vers des informations complémentaires (ex. : des publications ou des pages web) à la section « Voir également ».

  • Donnez une explication claire des paramètres de l’algorithme ainsi que de ses sorties (encore une fois, les exemples de GRASS et Taudem sont de bons exemples).

  • Ne modifiez pas les noms des paramètres ou de sorties. Si vous remarquez une erreur de syntaxe ou une mauvaise orthographe, reportez-la au niveau du bugtracker afin que les développeurs puissent corriger le problème directement dans le code du Géotraitement.

  • Ne listez pas les options disponibles dans la description de l’algorithme, les options sont déjà listées dans la description des paramètres.

  • N’ajoutez pas d’information sur le type de géométrie dans la description de l’algorithme ou de ses paramètres sans vous être assuré que cette information n’est pas déjà disponible dans la description des paramètres.