Outdated version of the documentation. Find the latest one here.

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:

../../_images/qgislogo.png

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

win osx

e naturalmente non dimentichiamo nix

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

  • 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

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)

  • 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