2. Writing Guidelines

In general, when creating reST documentation for the QGIS project, please follow the Python documentation style guidelines. For convenience, we provide a set of general rules we rely on for writing QGIS documentation below.

2.1. Writing Documentation

2.1.1. Headlines

To each webpage of the documentation corresponds a .rst file.

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. In QGIS Documentation, you should use following styles for chapter, section, subsection and minisec.

********
Chapter
********

Section
=======

Subsection
----------

Minisec
.......

Subminisec
^^^^^^^^^^

2.1.2. Lists

Lists are useful for structuring the text. Here are some simple rules common to all lists:

• Start all list items with a capital letter

• Do not use punctuation after list items that only contain a single simple sentence

• Use period ( . ) as punctuation for list items that consist of several sentences or a single compound sentence

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. Inline Tags

You can use tags to emphasize items.

• Menu GUI: to mark a complete sequence of menu selections, including selecting submenus and choosing a specific operation, or any subsequence of such a sequence.

  :menuselection:`menu --> submenu`
  

• Dialogs and Tab titles: Labels presented as part of an interactive user interface including window titles, tab titles, button and option labels.

  :guilabel:`title`
  

• Filenames and directories

  :file:`README.rst`
  

• Icons with popup text

  |icon| :sup:`popup_text`
  

  (see image below).

• Keyboard shortcuts

  :kbd:`Ctrl+B`
  

  will show Ctrl+B

  When describing keyboard shortcuts, the following conventions should be used:

  • Letter keys are displayed using uppercase: S

  • Special keys are displayed with an uppercase first letter: Esc

  • Key combinations are displayed with a + sign between keys, without spaces: Shift+R

• User text

  ``label``
  

2.1.5. Labels/references

Anchors inside the text can be used to create hyperlinks to sections or pages.

The example below creates the anchor of a section (e.g., Label/reference title)

.. _my_anchor:

Label/reference
---------------

To call the reference in the same page, use

see my_anchor_ for more information.

which will return:

see my_anchor for more information.

Notice that it will jump to the line/thing following the “anchor”. You do not need to use apostrophes, but you do need to have empty lines after the anchor.

Another way to jump to the same place from anywhere in the documentation is to use the :ref: role.

see :ref:`my_anchor` for more information.

which will create a link with the caption instead (in this case the title of this section!):

see Labels/references for more information.

So, reference 1 (my_anchor) and reference 2 (Labels/references). Because the reference often displays a full caption, it is not really necessary to use the word section. Note that you can also use a custom caption to describe the reference:

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

which returns:

see Label and reference for more information.

2.1.6. Figures and Images

Pictures

To insert an image, use

.. figure:: /static/common/logo.png
   :width: 10 em

which returns

Replacement

You can put an image inside text or add an alias to use everywhere. To use an image inside a paragraph, first create an alias in the source/substitutions.txt file:

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

and then call it in your paragraph:

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

This is how the example will be displayed:

My paragraph begins here with a nice logo .

To allow preview rendering in GitHub that is as close as possible to HTML rendering, you will also need to add the image replacement call at the end of the file you changed. This can be done by copy-pasting it from substitutions.txt or by executing the scripts/find_set_subst.py script.

Nota

Currently, to ensure consistency and help in the use of QGIS icons, a list of aliases is built and available in the Sostituzioni chapter.

Figure

.. _figure_logo:

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

   A caption: A logo I like

The result looks like this:

Fig. 2.23 A caption: A logo I like

To avoid conflicts with other references, always begin figure anchors with _figure_ and use terms that easily connect to the figure caption. While only the centered alignment is mandatory for the image, feel free to use any other options for figures (such as width, height, scale…) if needed.

The scripts will insert an automatically generated number before the caption of the figure in the generated HTML and PDF versions of the documentation.

To use a caption (see My caption) just insert indented text after a blank line in the figure block.

A figure can be referenced using the reference label like this:

see :numref:`figure_logo`

renders like this:

see Fig. 2.23

This is the preferred way of referencing figures.

Nota

For :numref: to work, the figure must have a caption.

It is possible to use :ref: instead of :numref: for reference, but this returns the full caption of the image.

see :ref:`figure_logo`

renders like this:

see A caption: A logo I like

Tables

A simple table can be coded like this

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

It will render like this:

x	y	z
1	2	3
4		5

Use a \ (backslash) followed by an empty space to leave an empty space.

You can also make more complicated tables and reference them:

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

The result:

Windows	macOS
e, naturalmente, non dimenticate

La mia tabella disegnata, badate che questo non è purtroppo considerato come una didascalia

Puoi fare riferimento ad esso in questo modo my_drawn_table.

Per tabelle ancora più complesse, è più comodo usare 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

The result:

Che cosa	Azione	Parola chiave	Descrizione
Test	Useful test	complexity	Geometria. Una di: Punto Linea

2.1.7. Indice

Un indice è un modo pratico per aiutare il lettore a trovare le informazioni in un documento. La documentazione di QGIS fornisce alcuni indici essenziali. Ci sono alcune regole che ci aiutano a fornire un insieme di indici che siano veramente utili (coerenti, consistenti e realmente collegati tra loro):

• Un indice dovrebbe essere leggibile, comprensibile e traducibile; un indice può essere composto da molte parole ma dovresti evitare qualsiasi carattere _, -… non necessario per collegarle, ad esempio, Loading layers invece di loading_layers o loadingLayers.

• Metti in maiuscolo solo la prima lettera dell’indice a meno che la parola non abbia un’ortografia particolare. Per esempio, Loading layers, Atlas generation, WMS, pgsql2shp.

• Tieni d’occhio la lista esistente Index list per riutilizzare l’espressione più conveniente con la giusta ortografia ed evitare inutili duplicati.

Esistono diversi tag di indice in RST. Puoi usare il tag inline :index: all’interno del testo normale:

QGIS can load several :index:`Vector formats` supported by GDAL ...

Oppure puoi usare il markup a livello di blocco .. index:: che rimanda all’inizio del paragrafo successivo. A causa delle regole menzionate sopra, si raccomanda di usare il tag block-level:

.. index:: WMS, WFS, Loading layers

Si raccomanda anche di usare parametri di indice come single, pair e see, per costruire una tabella di indice più strutturata e interconnessa. Vedi Index generating per maggiori informazioni sulla creazione di indici.

2.1.8. Commenti speciali

A volte, potresti voler enfatizzare alcuni punti della descrizione, sia per avvertire, ricordare o dare qualche suggerimento all’utente. In QGIS Documentation, usiamo le istruzioni speciali reST come .. warning::, .. seealso::`, ``. note:: e .. tip::. Queste istruzioni generano dei frame che evidenziano i tuoi commenti. Vedi ``Paragraph Level markup <https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#paragraph-level-markup>`_ per maggiori informazioni. Un titolo chiaro e appropriato è richiesto sia per gli avvisi che per i suggerimenti.

.. 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. Frammenti di codice

Potresti anche voler dare esempi e inserire frammenti di codice. In questo caso, scrivi il commento sotto una linea con la clausola :: inserita. Per una visualizzazione migliore, specialmente per applicare l’evidenziazione dei colori al codice in base alla sua lingua, usa la clausola code-block, ad esempio .. code-block:: xml. Maggiori dettagli in Showing code.

Nota

Mentre i testi nei riquadri delle note, dei suggerimenti e degli avvisi sono traducibili, sii consapevole che i riquadri dei blocchi di codice non ammettono la traduzione. Quindi evita i commenti non relativi al codice e mantieni i commenti il più corti possibile.

2.1.10. Note a piè di pagina

Nota bene: le note a piè di pagina non vengono riconosciute da nessun software di traduzione e non vengono nemmeno convertite correttamente in formato pdf. Quindi, se possibile, non usare le note a piè di pagina in nessuna documentazione.

Questo è per creare una nota a piè di pagina (mostrando come esempio [1])

blabla [1]_

Che punterà a:

[1]

Aggiornamenti dei plugin di base

2.2. Gestione delle schermate

2.2.1. Aggiungere nuove schermate

Ecco alcuni suggerimenti per creare nuove schermate dall’aspetto gradevole. Le immagini dovrebbero essere messe in una cartella image (img/) che si trova nella stessa cartella del file di riferimento .rst.

• Puoi trovare alcuni progetti QGIS pronti che vengono utilizzati per creare le schermate nella cartella ./qgis-projects di questo repository. In questo modo è più facile riprodurre le schermate per la prossima versione di QGIS. Questi progetti utilizzano i Sample Data (aka Alaska Dataset), che devono essere decompressi e collocati nella stessa cartella del QGIS-Documentation Repository.

• Riduci la finestra al minimo spazio necessario per mostrare la struttura (prendi tutto lo schermo per una piccola finestra modale > superfluo).

• Meno disordine c’è, meglio è (non c’è bisogno di attivare tutte le barre degli strumenti)

• Non ridimensionarli in un editor di immagini; la dimensione sarà impostata nei file .rst se necessario (ridimensionare le dimensioni senza aumentare correttamente la risoluzione > difficile).

• Taglia lo sfondo

• Imposta gli angoli superiori trasparenti se lo sfondo non è bianco

• Imposta la risoluzione di stampa a 135 dpi (per esempio in Gimp imposta la risoluzione di stampa Image ► Print size e salva). In questo modo le immagini saranno alle dimensioni originali in html e ad una buona risoluzione di stampa nel PDF. Puoi anche usare il comando ImageMagick convert per fare un batch di immagini:

  convert -units PixelsPerInch input.png -density 135 output.png
  

• Salvali come .png (per evitare gli artefatti di .jpeg)

• Lo screenshot dovrebbe mostrare il contenuto secondo quanto descritto nel testo

Suggerimento

Se sei su Ubuntu, puoi usare il seguente comando per rimuovere la funzione di menu globale e creare schermate di applicazioni più piccole con menu:

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

2.2.2. Screenshot tradotti

Ecco alcuni suggerimenti aggiuntivi per coloro che vogliono creare screenshot per una guida utente tradotta:

Le immagini tradotte dovrebbero essere messe in una cartella img/1/. Usa lo stesso nome di file della schermata inglese «originale».

2.3. Documentare gli algoritmi di Processing

Se vuoi scrivere la documentazione per gli algoritmi di Processing, considera queste linee guida:

• I file di aiuto dell’algoritmo di Processing fanno parte della Guida utente di QGIS, quindi usano la stessa formattazione della Guida utente e dell’altra documentazione.

• La documentazione di ogni algoritmo dovrebbe essere messa nella corrispondente cartella provider e nel file group, per esempio l’algoritmo Voronoi polygon appartiene al provider QGIS e al gruppo vectorgeometry. Quindi il file corretto per aggiungere la descrizione è: source/docs/user_manual/processing_algs/qgis/vectorgeometry.rst.

  Nota

  Prima di iniziare a scrivere la guida, controllare se l’algoritmo è già descritto. In tal caso, è possibile migliorare la descrizione esistente.

• È estremamente importante che ogni algoritmo abbia un ancora che corrisponde al nome del provider + il nome univoco dell’algoritmo stesso. Questo permette al pulsante Help di aprire la pagina di aiuto della sezione corretta. L’ancora dovrebbe essere posta sopra il titolo, ad esempio (vedi anche la sezione Labels/references):

  .. _qgisvoronoipolygons:
  
  Voronoi polygons
  ----------------
  

  Per trovare il nome dell’algoritmo puoi semplicemente passare il mouse sull’algoritmo nella casella degli strumenti di Processing.

• Evita di usare «Questo algoritmo fa questo e quello…» come prima frase della descrizione dell’algoritmo. Cerca di usare espressioni più generali come:

  Takes a point layer and generates a polygon layer containing the...
  

• Evita di descrivere cosa fa l’algoritmo replicando il suo nome e per favore non replicare il nome del parametro nella descrizione del parametro stesso. Per esempio se l’algoritmo è Voronoi polygon puoi descrivere il Layer in ingresso come Layer da cui calcolare il poligono.

• Indica nella descrizione se l’algoritmo ha una scorciatoia predefinita in QGIS o supporta la modifica sul posto

• Aggiungete immagini! Un’immagine vale più di mille parole! Usa il formato .png e segui le linee guida generali per la documentazione (vedi la sezione Figures and Images per maggiori informazioni). Metti il file immagine nella cartella corretta, cioè la cartella img accanto al file .rst che stai modificando.

• Se necessario, aggiungi dei link nella sezione «Vedi anche» che forniscono informazioni aggiuntive sull’algoritmo (ad esempio, pubblicazioni o pagine web). Aggiungi la sezione «Vedi anche» solo se c’è veramente qualcosa da vedere. Come buona pratica, la sezione «Vedi anche» può essere riempita con link ad algoritmi simili.

• Dai una spiegazione chiara dei parametri e dei risultati dell’algoritmo: prendi ispirazione dagli algoritmi esistenti.

• Evita di duplicare la descrizione dettagliata delle opzioni dell’algoritmo. Aggiungi queste informazioni nella descrizione del parametro.

• Evita di aggiungere informazioni sul tipo di geometria vettoriale nella descrizione dell’algoritmo o del parametro, poiché queste informazioni sono già disponibili nelle descrizioni dei parametri.

• Aggiungi il valore predefinito del parametro, ad esempio:

  * - **Number of points**
    - ``NUMBER_OF_POINTS``
    - [number]
  
      Default: 1
    - Number of points to create
  

• Descrivi il tipo di dati in ingresso supportati dai parametri. Ci sono diversi tipi disponibili che puoi scegliere:

  Tipo di parametro/risultato	Descrizione	Indicatore visuale
  Layer vettore punto	vector: point
  Layer vettore linea	vector: line
  Layer vettoriale poligono	vector: polygon
  Layer vettoriale generico	vector: any
  Campo vettoriale numerico	tablefield: numeric
  Campo vettoriale stringa	tablefield: string
  Campo generico vettore	tablefield: any
  Layer raster	raster
  Banda raster	raster band
  File HTML	html
  Layer tabella	table
  Espressione	expression
  Geometria punto	coordinates
  Estensione	extent
  SR	crs
  Numerazione	enumeration
  Elenco	list
  Numero	number
  Stringa	string
  Booleano	boolean
  Percorso cartella	folder
  File	file
  Matrice	matrix
  Layer	layer
  Stesso tipo in uscita del tipo in ingresso	same as input
  Definizione	definition
  Punto	point
  Multilayer	multipleLayers
  Intervallo	range
  Autoconfigurazione	authconfig
  Mesh	mesh
  Layout	layout
  LayoutItem	layoutitem
  Colore	color
  Scala	scale

• Studia un algoritmo esistente e ben documentato, e copia tutti i layout utili.

• Quando hai finito, segui le linee guida descritte in Una contribuzione passo dopo passo per confermare le tue modifiche e fare una richiesta di Pull.

Ecco un esempio di un existing algorithm per esserti d’aiuto con il layout e la descrizione:

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