2. Scrivere Linee Guida

In generale, quando si crea documentazione reST per il progetto QGIS, si prega di seguire le Python documentation style guidelines <https://devguide.python.org/documenting/>`_. Per comodità, forniamo di seguito un insieme di regole generali su cui ci basiamo per scrivere la documentazione di QGIS.

2.1. Scrivere la Documentazione

2.1.1. Titoli di testa

Ad ogni pagina web della documentazione corrisponde un file .rst.

Le sezioni utilizzate per strutturare il testo sono identificate attraverso il loro titolo che è sottolineato (e sottolineato per il primo livello). I titoli dello stesso livello devono usare lo stesso carattere per la sottolineatura. Nella documentazione di QGIS, si dovrebbero usare i seguenti stili per capitolo, sezione, sotto sezione e minisec.

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

Section
=======

Subsection
----------

Minisec
.......

Subminisec
^^^^^^^^^^

2.1.2. Liste

Le liste sono utili per strutturare il testo. Ecco alcune semplici regole comuni a tutte le liste:

• Iniziare tutte le voci dell’elenco con una lettera maiuscola

• Non usare la punteggiatura dopo le voci della lista che contiene solo una singola frase semplice

• Usa il punto ( . ) come punteggiatura per le voci della lista che consistono in più frasi o in una singola frase composta

2.1.3. Indentazione

L’indentazione in ReStructuredText dovrebbe essere allineata con l’elenco o il marcatore del markup. È anche possibile creare citazioni in blocco con indentazione. Vedere la 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. Tag in linea

Puoi usare i tag per enfatizzare gli oggetti.

• Menu GUI: per contraddistinguere una sequenza completa di selezioni di menu, compresa la selezione di sottomenu e la scelta di un’operazione specifica, o una qualsiasi successione di tale sequenza.

  :menuselection:`menu --> submenu`
  

• Titoli delle finestre di dialogo e delle schede: Etichette presentate come parte di un’interfaccia utente interattiva, compresi i titoli delle finestre, delle schede, dei pulsanti e delle etichette indicanti le opzioni.

  :guilabel:`title`
  

• Nomi file e cartelle

  :file:`README.rst`
  

• Icone con testo a comparsa

  |icon| :sup:`popup_text`
  

  (vedi image sotto).

• Scorciatoie da tastiera

  :kbd:`Ctrl+B`
  

  mostrerà Ctrl+B.

  Quando si descrivono le scorciatoie da tastiera, si dovrebbero usare le seguenti convenzioni:

  • I tasti delle lettere sono visualizzati usando le maiuscole: S

  • I tasti speciali sono visualizzati con una prima lettera maiuscola: Esc

  • Le combinazioni di tasti sono visualizzate con un segno + tra i tasti, senza spazi: Shift+R

• Testo utente

  ``label``
  

2.1.5. Etichette/riferimenti

Le ancore all’interno di un testo possono essere usate per creare collegamenti ipertestuali a sezioni o pagine.

L’esempio seguente crea l’ancora a una sezione (ad esempio, Etichetta/titolo di riferimento)

.. _my_anchor:

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

Per fare riferimento nella stessa pagina, usa

see my_anchor_ for more information.

che restituirà:

vedi my_anchor per maggiori informazioni.

Notate che salterà alla linea/cosa che segue “anchor”. Non è necessario usare apostrofi, ma è necessario avere linee vuote dopo l’ancora.

Un altro modo per saltare allo stesso posto da qualsiasi punto della documentazione è usare il riferimento :ref:.

see :ref:`my_anchor` for more information.

che creerà invece un link con la didascalia (in questo caso il titolo di questa sezione!):

vedi Etichette/riferimenti per maggiori informazioni.

Quindi, riferimento 1 (my_anchor) e riferimento 2 (Etichette/riferimenti). Poiché il riferimento spesso mostra una didascalia completa, non è realmente necessario usare la parola sezione. Nota che puoi anche usare una didascalia personalizzata per descrivere il riferimento:

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

che restituisce:

vedi Label and reference per maggiori informazioni.

2.1.6. Figure e Immagini

Immagini

Per inserire un’immagine, usa

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

che restituisce

Sostituzione

Puoi mettere un’immagine all’interno del documento o aggiungere un alias da usare ovunque. Per usare un’immagine all’interno di un paragrafo, prima crea un alias nel file source/substitutions.txt:

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

e poi richiamarla nel tuo paragrafo:

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

Questo è il modo in cui l’esempio verrà visualizzato:

Il mio paragrafo inizia qui con un bel logo .

Per permettere una visualizzazione dell’anteprima in GitHub che sia la più vicina possibile alla visualizzazione HTML, dovrai anche aggiungere la chiamata di sostituzione dell’immagine alla fine del file che hai modificato. Questo può essere fatto facendo un copia-incolla da substitutions.txt o eseguendo lo script scripts/find_set_subst.py.

Nota

Attualmente, per assicurare la coerenza e aiutare nell’uso delle icone QGIS, una lista di alias è stata realizzata e disponibile nel capitolo Sostituzioni.

Figura

.. _figure_logo:

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

   A caption: A logo I like

Il risultato si presenta così:

Fig. 2.19 Una didascalia: Un logo che mi piace

Per evitare conflitti con altri riferimenti, inizia sempre le ancore delle figure con _figure_ e usa termini che si collegano facilmente alla didascalia della figura. Mentre solo l’allineamento centrato è obbligatorio per l’immagine, sentiti libero di usare qualsiasi altra opzione per le figure (come larghezza, altezza, scala…) se necessario.

Gli script inseriranno un numero generato automaticamente prima della didascalia della figura nelle versioni HTML e PDF generate della documentazione.

Per usare una didascalia (vedi La mia didascalia) basta inserire del testo rientrato dopo una riga vuota nel blocco della figura.

Una figura può essere referenziata usando l’etichetta di riferimento in questo modo:

see :numref:`figure_logo`

viene visualizzata in questo modo:

vedi Fig. 2.19

Questo è il modo preferito di referenziare le figure.

Nota

Perché :numref: funzioni, la figura deve avere una didascalia.

È possibile usare :ref: invece di :numref: per riferimento, ma questo restituisce la didascalia completa dell’immagine.

see :ref:`figure_logo`

viene visualizzata in questo modo:

vedi Una didascalia: Un logo che mi piace

Tabelle

Una tabella semplice può essere codificata in questo modo

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

Sarà visualizzata in questo modo:

x	y	z
1	2	3
4		5

Usa un \ (backslash) seguito da uno spazio vuoto per lasciare uno spazio vuoto.

Puoi anche fare tabelle più complicate e farvi riferimento:

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

Il risultato:

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

Il risultato:

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/OGR ...

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 preparati che sono usati per creare screenshot nella cartella ./qgis-projects di questo repository. Questo rende più facile riprodurre gli screenshot per la prossima versione di QGIS. Questi progetti usano il QGIS Sample Data (aka Alaska Dataset), che dovrebbe essere messo 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 Etichette/riferimenti):

  .. _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 Figure e Immagini 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