Linee guida per la documentazione¶

Introduzione¶

Queste sono le linee guida circa l’uso del software rst usato per la documentazione di QGIS. La documentazione verrà compilata automaticamente sul server 0, alle ore 08:00, 16:00 del fuso PDT (Pacific Daylight Time). Lo stato attuale è disponibile sull’indirizzo http://docs.qgis.org.

vedere anche su: http://sphinx.pocoo.org/markup/inline.html o il file convention.rst

In generale, quando si crea la documentazione RST per il progetto QGIS, si prega di seguire le `linee guida dello stile di documentazione Python:<http://docs.python.org/devguide/documenting.html>`_.

Utilizzo dei titoli¶

Per aggiungere nuovi titoli, è necessario utilizzare i seguenti stili per capitolo, sezione, sottosezione e minisezioni.

titoli

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

Section
=======

Subsection
----------

Minisec
.......

etichette inline¶

scorciatoie di tastiera
```
:kbd:`ctrl B`
```
mostrerà Ctrl B
Interfaccia grafica del menu
```
:menuselection:`menu --> submenu`
```
Nome file:
```
:file:`README.rst`
```
Icona senza il popup della descrizione
```
|icon| :sup:`popup_text`
```
(vedere immagine sotto).
Titolo della finestra di dialogo e della scheda
```
:guilabel:`title`
```
Testo utente
```
``label``
```

Note a pié di pagina¶

Si prega di notare che le note a pié di pagina non sono riconosciute da alcun software di traduzione e non è inoltre possibile convertirle correttamente in formato pdf. Quindi, non utilizzate le note all’interno di qualsiasi documentazione.

Creazione di una nota a pié di pagina

blabla [1]_

Il quale punterà a

[1]
Aggiornamenti dei plugin di base

Etichetta/riferimento¶

Per creare un riferimento a qualcosa

.. _my_anchor:

Label/reference
===============

Questo chiamerà il riferimento nella stessa pagina

see my_anchor_ for more information. Notice how it will jump to
the following line/thing following the 'anchor'.
Normally to declare this label you do not need to use apastroph's but
you do need to use empty lines before and after the anchor. If you use
:ref:`my_anchor` it will display the caption instead
(In this case the title of this section!)

Il riferimento 1 (my_anchor) e il riferimento 2 Etichetta/riferimento

Poiché spesso il riferimento visualizza una didascalia completa, non c’è bisogno di utilizzare la parola sezione

see :ref:`my_anchor`

Figura ed immagine¶

Figura

.. _figure_readme_1:

.. only:: html

   **Figure Readme 1:**

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

   A caption: A logo I like

Il risultato dovrebbe essere come questo:

Figure Readme 1:

Una didascalia: Un logo che mi piace

Utilizzare .. solo:: html per applicare il numero di figura (Figura Readme 1) visibile solo nei file html. Gli script inseriranno un numero automatico generato prima della didascalia della figura in pdf.

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

Il riferimento alla figura può essere fatto in due modi: con l’etichetta di riferimento come questo

(see Figure_Readme_1_).

Mostrerà l’ancora Figure_Readme_1. È possibile utilizzare il maiuscolo, se vuoi. Può essere utilizzato nello stesso .rst documento ma non in altri documenti .rst.

Non è più possibile utilizzare il riferimento come questo, perché in html si perde il riferimento alla voce (ora si punta a prima della Figura 1 Readme:

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!

Tabelle¶

una tabella semplice

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

Usa un \ seguito da uno spazio vuoto ‘ ‘ per lasciare uno spazio vuoto.

È inoltre possibile utilizzare le tabelle più complesse disegnando utilizzando riferimenti e tutti

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

Il risultato

Windows	Mac OS X

e naturalmente non dimentichiamo

La mia tabella disegnata, intendiamoci questo non è purtroppo considerata una didascalia

Puoi referenziarla come questo my_drawn_table_1.

Immagini¶

Immagine

.. image:: /static/common/qgislogo.png
   :width: 10 em

Sostituzione¶

È possibile inserire un’immagine all’interno del testo o aggiungere un alias da utilizzare ovunque. Per usare un’immagine all’interno di un paragrafo, basta creare un alias da qualche parte

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

e chiamarla nel vostro punto

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

Ecco come diventa questo esempio:

il mio paragrafo comincia qui, con un bel logo .

Indice¶

Esistono diversi tag indice nel RST. Per essere in grado di tradurre l’indice, è necessario integrarlo nel testo normale, in questo caso usare la sintassi:

QGIS allows to load several :index:`Vector formats` supported by GDAL/OGR ...

Se il termine non deve essere tradotto, usa questa sintassi:

.. index:: WMS, WFS, WCS, CAT, SFS, GML, ...

Aggiungi una nuova schermata¶

Ecco alcuni suggerimenti per la creazione di nuove schermate. Per la guida vai in:file: ./resources/it/user_manual/

lo stesso ambiente per tutte le schermate (stesso sistema operativo, stessa decorazione delle finestre e stessa dimensione del carattere)
ridurre la finestra allo spazio minimo necessario per mostrare la caratteristica (catturare la schermata su una finestra piccola)
è meglio avere una schermata meno complessa (ad esempio non abilitare tutte le barre degli strumenti)
non ridimensionarle in un editor per le immagini, la dimensione verrà impostata nei file rst (altrimenti verrà fuori una brutta immagine)
ritagliare lo sfondo
Impostare la risoluzione per la stampa a 135 dpi (in questo modo, se non è impostata nessuna dimensione nel file rst, le immagini saranno alla loro dimensione originale in html e ad una buona risoluzione per il PDF)
salvarle nel formato png (no jpeg)
la schermata dovrebbe mostrare ciò di cui si sta parlando nel testo
puoi trovare alcuni progetti QGIS che sono già stati utilizzati per creare schermate in :file: /qgis-projects. Questo rende più facile riprodurre le immagini per la prossima versione di QGIS. Questi progetti utilizzano l’insieme di dati campione che dovrebbe essere inserito nella stessa cartella del repository QGIS-Documentazione.
Utilizzare il seguente comando per rimuovere la funzione menu globale in Ubuntu e per creare schermate delle applicazioni con il menu.

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

Tradurre le schermate¶

Di seguito alcuni suggerimenti per creare schermate per la tua guida tradotta. Andranno in ./resources/<your language>/user_manual/

lo stesso ambiente per tutte le schermate (stesso sistema operativo, stessa decorazione delle finestre e stessa dimensione del carattere)
utilizza i progetti |qg|nel repository QGIS-Documentazione (in :file: `./ qgis_projects`). Questi sono stati utilizzati per produrre le schermate originali” nel manuale. L’insieme di dati campione |qg| dovrebbe essere nella stessa cartella del repository QGIS-documentazione.
usare la stessa dimensione della versione in inglese, altrimenti saranno “ristrette” e verranno brutte. Se hai bisogno di una dimensione differente, non dimenticare di scriverlo nel codice rst della tua lingua.
ridurre la finestra allo spazio minimo necessario per mostrare la caratteristica (catturare la schermata su una finestra piccola)
è meglio avere una schermata meno complessa (ad esempio non abilitare tutte le barre degli strumenti)
non ridimensionarle in un editor per le immagini, la dimensione verrà impostata nei file rst (altrimenti verrà fuori una brutta immagine)
ritagliare lo sfondo
salvarle nel formato png (no jpeg)
la schermata dovrebbe mostrare ciò di cui si sta parlando nel testo

Documentare gli algoritmi di Processing¶

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

non sovrascrivere i file di aiuto esistenti con file da altre fonti (ad esempio QGIS sorgenti o repository di aiuto Processing), questi file hanno diversi formati
I file di aiuto sugli algoritmi di Processing fanno parte della Guida Utente di Qgis, usare quindi la stessa formattazione della Guida Utente e relativa documentazione
avoid use “This algoritm does this and that...” as first sentence in algorithm description. Try to use more general words like in TauDEM or GRASS algoritms help
aggiungi immagini se necessario. Usa il formato PNG e attieniti alle linee guida generali per la documentazione.
se necessario, segna collegamenti a informazioni aggiuntive (ad esempio pubblicazioni o pagine web) per la sezione “Vedi anche”
give clear explanation for algorithm parameters and outputs (again GRASS and TauDEM are good examples).
non modificare i nomi dei parametri o dei risultati. Se hai trovato errori di battitura o di ortografia sbagliato - segnalo nel bugracker, cosicche gli sviluppatori possono risolvere questo problema anche nel codice di Processing
don’t list availbale options in algortihm description, options already listed in parameter description.
non aggiungere informazioni sul tipo di vettore nella descrizione dell’algoritmo o del parametro senza motivo valido, essendo queste informazioni già disponibili nella descrizione dei parametri