Recommandations pour 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

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

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

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:

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
et bien sûr, ne pas oublier

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

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