Importante

La traduzione è uno sforzo comunitario you can join. Questa pagina è attualmente tradotta al 87.13%.

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.

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. Precede section titles with a blank line. In QGIS Documentation, you should use following styles for chapter, section, subsection and 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

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

• Layers, databases, tables or columns names

  When referring to layers, databases, tables or columns, format as inline code:

  ``layer name``
  ``database_name``
  ``table_name``
  ``column_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

Icon substitution

You can add an image inside a text paragraph (e.g., as a tool icon). To do so, you first need to create an alias (also named substitution), which is a reference name used to display the icon. To ensure consistency across the documents and help in the use of the icons, we maintain a list in the substitutions.txt file at the root of this repository. Find more details in the Sostituzioni chapter.

Using an icon substitution is usually achieved through these steps:

1. Add the icon substitution in the substitutions.txt file as below. If a substitution already exists for the icon you want to use, then skip this step.

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

2. Call it in your paragraph:

   My paragraph begins here with |logo|.
   

3. Add (again) the icon substitution at the end of the file you are modifying. This helps connecting the replacement text with the actual image, and can be done by copy-pasting it from substitutions.txt or by executing the scripts/find_set_subst.py script.

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

   My paragraph begins here with .

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

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

2.1.7. Tabelle

You can make a simple table like this:

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

Sarà visualizzata in questo modo:

x	y	z
1	2	3
4		5

Tables should have a caption. You can use an explicit reST «table» directive to add a caption to simple tables or grid tables. Add the caption on the same line as the directive and indent the table at least one space.

You can also add a hyperlink target before a table in order to reference it elsewhere. To avoid conflicts with other references, always begin hyperlink targets with _table_ and use terms relevant to the table caption.

Here is an example of a more complicated grid table with a caption and a hyperlink target:

.. _table-grid-caption:

.. table:: Grid table with caption

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

Il risultato:

Tabella 2.2 Grid table with caption

Windows	macOS
e, naturalmente, non dimenticate

You may find it easier to use list tables or CSV tables to make complex tables. Add the caption after the list-table or csv-table directive.

Here is an example of a list table with a caption and a hyperlink target:

.. _table-list-caption:

.. list-table:: List table with caption
   :header-rows: 1
   :widths: 20 20 20 40

   * - What
     - Purpose
     - Key word
     - Description
   * - **Test**
     - ``Useful test``
     - complexity
     - Geometry.  One of:

       * Point
       * Line

Il risultato:

Tabella 2.3 List table with caption

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

Use :numref: roles to reference tables like this:

see :numref:`table-grid-caption` or :numref:`table-list-caption`

Il risultato:

see Tabella 2.2 or Tabella 2.3

Nota

You must add a caption to your table in order to create a cross reference with the :numref: role.

2.1.8. Index

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.

Several index tags exist in reST. You can use the inline :index: tag within normal text:

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.9. Commenti speciali

A volte, potresti voler enfatizzare alcuni punti della descrizione, sia per avvertire, ricordare o dare alcuni suggerimenti all’utente. Nella documentazione di QGIS, utilizziamo istruzioni speciali reST come .. warning::, .. seealso::, .. note:: e .. tip::. Queste istruzioni generano cornici che evidenziano i tuoi commenti. Per ulteriori informazioni, consultare Paragraph Level markup . È necessario un titolo chiaro e appropriato 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.10. 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

Text in special comments will be translated, but text in code-block frames will not be translated. So keep comments in code blocks as short as possible and avoid comments unrelated to code.

2.1.11. Note a piè di pagina

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.

• You can find some prepared QGIS projects that are used to create screenshots in the ./qgis-projects folder of this repository. This makes it easier to reproduce screenshots for the next version of QGIS. These projects use the QGIS Sample Data (aka Alaska Dataset), which should be unzipped and placed in the same folder as the 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

• Set print size resolution to 135 dpi (e.g., in GIMP scale down the image using Image ► Scale Image and setting «X/Y» to 135 pixels/in, and export it through File ► Export…). This way, images will be at original size in HTML and at a good print resolution in the PDF.

  Puoi anche usare il comando convert di ImageMagick per elaborare un gruppo 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:

Translated images should be placed in a img/<your_language>/ folder. Use the same filename as the “original” English screenshot.

2.3. Documentare gli algoritmi di Processing

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

• Processing algorithm help files are part of QGIS User Guide, so use the same formatting as the User Guide and other documentation.

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

• It is extremely important that each algorithm has an anchor that corresponds to the provider name + the unique name of the algorithm itself. This allows the Help button to open the Help page of the correct section. The anchor should be placed above the title, e.g. (see also the Etichette/riferimenti section):

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

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

• Avoid using «This algorithm does this and that…» as the first sentence in the algorithm description. Try to use more general expressions like:

  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.

• Add the default value of the parameter, e.g.:

  * - **Number of points**
    - ``NUMBER_OF_POINTS``
    - [numeric: integer]
  
      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 puntuale	vector: point
  Layer vettore linea	vector: line
  Layer vettoriale poligonale	vector: polygon
  Tutti i layer vettoriali spaziali	vector: geometry
  Layer vettoriale senza geometria	vector: table
  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
  Espressione	expression
  Line geometry	geometry: line
  Geometria punto	coordinates
  Estensione	extent
  CRS	crs
  Numerazione	enumeration
  Elenco	list
  Valore intero	numeric: integer
  Valore decimale	numeric: double
  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
  Layer Mappa	layer list
  Intervallo	range
  Autoconfigurazione	authconfig
  Mesh	mesh
  Layout	layout
  LayoutItem	layoutitem
  Colore	color
  Scala	scale
  Tema Mappa	map theme

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

Here is an example of an existing algorithm to help you with the layout and the description:

.. _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
   :class: longtable

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