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¶

Here are some hints to create new, nice looking screenshots. For the user guide they go into ./resources/en/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)
don’t resize them in an image editor, the size will be set into the rst files if necessary (downscaling the dimensions without properly upping the resolution > ugly)
ritagliare lo sfondo
Set print size resolution to 135 dpi (this way, if no size is set in the rst files, images will be at original size in html and at a good print resolution in the PDF)
salvarle nel formato png (no jpeg)
la schermata dovrebbe mostrare ciò di cui si sta parlando nel testo
you can find some prepared QGIS -projects that were used before to create screenshots in ./qgis-projects. This makes it easier to reproduce screenshots for the next version of QGIS. These projects use the QGIS sample dataset which should be placed in the same folder as the QGIS-Documentation Repository.
Use the following command to remove the global menu function in Ubuntu to create smaller application screens with menu’s.

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

Tradurre le schermate¶

Here are some hints to create screenshots for your translated user guide. They will go into ./resources/<your language>/user_manual/

lo stesso ambiente per tutte le schermate (stesso sistema operativo, stessa decorazione delle finestre e stessa dimensione del carattere)
use the QGIS -projects included in QGIS-Documentation repository (in ./qgis_projects ). These were used to produce the ‘original’ screenshots in the manual. The QGIS Sample dataset should be placed in the same folder as the QGIS-Documentation Repository.
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

Documenting Processing algorithms¶

If you want to write documentation for Processing algorithms consider this guidelines:

don’t overwrite existing help files by files from other sources (e.g. QGIS source tree or Processing-Help repository), this files have different formats
Processing algorithm help files are part of QGIS User Guide, so use same formatting as User Guide and other documentation
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
add images if needed. Use PNG format and follow general guidelines for documentation.
if necessary add links to additional information (e.g. publications or web-pages) to the “See also” section
give clear explanation for algorithm parameters and outputs (again GRASS and TauDEM are good examples).
don’t edit parameter or output names. If you found typo or wrong spelling — report this in bugracker, so developers can fix this in Processing code too
don’t list available options in algorithm description, options already listed in parameter description.
don’t add information vector geometry type in algorithm or parameter description without compelling reason as this information already available in parameter description