Importante

unireLa traduzione è uno sforzo comunitario you can join. Questa pagina è attualmente tradotta al 100.00%.

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

  • Nomi Layer Quando ci si riferisce ai layer, formattarli come codice in linea:

    ``layer name``

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

../../_images/logo.png

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 nice_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ì:

../../_images/logo.png

Fig. 2.23 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.23

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

win

osx

e, naturalmente, non dimenticate nix

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

Obiettivo

Parola chiave

Descrizione

Prova

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. Blocchi 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:

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

    pointLayer

    Layer vettore linea

    vector: line

    lineLayer

    Layer vettoriale poligonale

    vector: polygon

    polygonLayer

    Layer vettoriale generico

    vector: any

    Campo vettoriale numerico

    tablefield: numeric

    fieldFloat

    Campo vettoriale stringa

    tablefield: string

    fieldText

    Campo generico vettore

    tablefield: any

    Layer raster

    raster

    rasterLayer

    Banda raster

    raster band

    File HTML

    html

    Layer tabella

    table

    tableLayer

    Espressione

    expression

    expression

    Geometria punto

    coordinates

    Estensione

    extent

    CRS

    crs

    setProjection

    Numerazione

    enumeration

    selectString

    Elenco

    list

    Numero

    number

    selectNumber

    Stringa

    string

    inputText

    Booleano

    boolean

    checkbox

    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