Documentation/translations/it_IT/doc-guide/sphinx.rst - linux - Git at Google

 .. include:: ../disclaimer-ita.rst

 .. note:: Per leggere la documentazione originale in inglese:
 	  :ref:`Documentation/doc-guide/index.rst <doc_guide>`

 .. _it_sphinxdoc:

 Introduzione
 ============

 Il kernel Linux usa `Sphinx`_ per la generazione della documentazione a partire
 dai file `reStructuredText`_ che si trovano nella cartella ``Documentation``.
 Per generare la documentazione in HTML o PDF, usate comandi ``make htmldocs`` o
 ``make pdfdocs``. La documentazione così generata sarà disponibile nella
 cartella ``Documentation/output``.

 .. _Sphinx: http://www.sphinx-doc.org/
 .. _reStructuredText: http://docutils.sourceforge.net/rst.html

 I file reStructuredText possono contenere delle direttive che permettono di
 includere i commenti di documentazione, o di tipo kernel-doc, dai file
 sorgenti.
 Solitamente questi commenti sono utilizzati per descrivere le funzioni, i tipi
 e l'architettura del codice. I commenti di tipo kernel-doc hanno una struttura
 e formato speciale, ma a parte questo vengono processati come reStructuredText.

 Inoltre, ci sono migliaia di altri documenti in formato testo sparsi nella
 cartella ``Documentation``. Alcuni di questi verranno probabilmente convertiti,
 nel tempo, in formato reStructuredText, ma la maggior parte di questi rimarranno
 in formato testo.

 .. _it_sphinx_install:

 Installazione Sphinx
 ====================

 I marcatori ReST utilizzati nei file in Documentation/ sono pensati per essere
 processati da ``Sphinx`` nella versione 1.3 o superiore. Se desiderate produrre
 un documento PDF è raccomandato l'utilizzo di una versione superiore alle 1.4.6.

 Esiste uno script che verifica i requisiti Sphinx. Per ulteriori dettagli
 consultate :ref:`it_sphinx-pre-install`.

 La maggior parte delle distribuzioni Linux forniscono Sphinx, ma l'insieme dei
 programmi e librerie è fragile e non è raro che dopo un aggiornamento di
 Sphinx, o qualche altro pacchetto Python, la documentazione non venga più
 generata correttamente.

 Un modo per evitare questo genere di problemi è quello di utilizzare una
 versione diversa da quella fornita dalla vostra distribuzione. Per fare questo,
 vi raccomandiamo di installare Sphinx dentro ad un ambiente virtuale usando
 ``virtualenv-3`` o ``virtualenv`` a seconda di come Python 3 è stato
 pacchettizzato dalla vostra distribuzione.

 .. note::

    #) Le versioni di Sphinx inferiori alla 1.5 non funzionano bene
       con il pacchetto Python docutils versione 0.13.1 o superiore.
       Se volete usare queste versioni, allora dovere eseguire
       ``pip install 'docutils==0.12'``.

    #) Viene raccomandato l'uso del tema RTD per la documentazione in HTML.
       A seconda della versione di Sphinx, potrebbe essere necessaria
       l'installazione tramite il comando ``pip install sphinx_rtd_theme``.

    #) Alcune pagine ReST contengono delle formule matematiche. A causa del
       modo in cui Sphinx funziona, queste espressioni sono scritte
       utilizzando LaTeX. Per una corretta interpretazione, è necessario aver
       installato texlive con i pacchetti amdfonts e amsmath.

 Riassumendo, se volete installare la versione 1.4.9 di Sphinx dovete eseguire::

        $ virtualenv sphinx_1.4
        $ . sphinx_1.4/bin/activate
        (sphinx_1.4) $ pip install -r Documentation/sphinx/requirements.txt

 Dopo aver eseguito ``. sphinx_1.4/bin/activate``, il prompt cambierà per
 indicare che state usando il nuovo ambiente. Se aprite un nuova sessione,
 prima di generare la documentazione, dovrete rieseguire questo comando per
 rientrare nell'ambiente virtuale.

 Generazione d'immagini
 ----------------------

 Il meccanismo che genera la documentazione del kernel contiene un'estensione
 capace di gestire immagini in formato Graphviz e SVG (per maggior informazioni
 vedere :ref:`it_sphinx_kfigure`).

 Per far si che questo funzioni, dovete installare entrambe i pacchetti
 Graphviz e ImageMagick. Il sistema di generazione della documentazione è in
 grado di procedere anche se questi pacchetti non sono installati, ma il
 risultato, ovviamente, non includerà le immagini.

 Generazione in PDF e LaTeX
 --------------------------

 Al momento, la generazione di questi documenti è supportata solo dalle
 versioni di Sphinx superiori alla 1.4.

 Per la generazione di PDF e LaTeX, avrete bisogno anche del pacchetto
 ``XeLaTeX`` nella versione 3.14159265

 Per alcune distribuzioni Linux potrebbe essere necessario installare
 anche una serie di pacchetti ``texlive`` in modo da fornire il supporto
 minimo per il funzionamento di ``XeLaTeX``.

 .. _it_sphinx-pre-install:

 Verificare le dipendenze Sphinx
 -------------------------------

 Esiste uno script che permette di verificare automaticamente le dipendenze di
 Sphinx. Se lo script riesce a riconoscere la vostra distribuzione, allora
 sarà in grado di darvi dei suggerimenti su come procedere per completare
 l'installazione::

 	$ ./scripts/sphinx-pre-install
 	Checking if the needed tools for Fedora release 26 (Twenty Six) are available
 	Warning: better to also install "texlive-luatex85".
 	You should run:

 		sudo dnf install -y texlive-luatex85
 		/usr/bin/virtualenv sphinx_1.4
 		. sphinx_1.4/bin/activate
 		pip install -r Documentation/sphinx/requirements.txt

 	Can't build as 1 mandatory dependency is missing at ./scripts/sphinx-pre-install line 468.

 L'impostazione predefinita prevede il controllo dei requisiti per la generazione
 di documenti html e PDF, includendo anche il supporto per le immagini, le
 espressioni matematiche e LaTeX; inoltre, presume che venga utilizzato un
 ambiente virtuale per Python. I requisiti per generare i documenti html
 sono considerati obbligatori, gli altri sono opzionali.

 Questo script ha i seguenti parametri:

 ``--no-pdf``
 	Disabilita i controlli per la generazione di PDF;

 ``--no-virtualenv``
 	Utilizza l'ambiente predefinito dal sistema operativo invece che
 	l'ambiente virtuale per Python;


 Generazione della documentazione Sphinx
 =======================================

 Per generare la documentazione in formato HTML o PDF si eseguono i rispettivi
 comandi ``make htmldocs`` o ``make pdfdocs``. Esistono anche altri formati
 in cui è possibile generare la documentazione; per maggiori informazioni
 potere eseguire il comando ``make help``.
 La documentazione così generata sarà disponibile nella sottocartella
 ``Documentation/output``.

 Ovviamente, per generare la documentazione, Sphinx (``sphinx-build``)
 dev'essere installato. Se disponibile, il tema *Read the Docs* per Sphinx
 verrà utilizzato per ottenere una documentazione HTML più gradevole.
 Per la documentazione in formato PDF, invece, avrete bisogno di ``XeLaTeX`
 e di ``convert(1)`` disponibile in ImageMagick (https://www.imagemagick.org).
 Tipicamente, tutti questi pacchetti sono disponibili e pacchettizzati nelle
 distribuzioni Linux.

 Per poter passare ulteriori opzioni a Sphinx potete utilizzare la variabile
 make ``SPHINXOPTS``. Per esempio, se volete che Sphinx sia più verboso durante
 la generazione potete usare il seguente comando ``make SPHINXOPTS=-v htmldocs``.

 Potete eliminare la documentazione generata tramite il comando
 ``make cleandocs``.

 Scrivere la documentazione
 ==========================

 Aggiungere nuova documentazione è semplice:

 1. aggiungete un file ``.rst`` nella sottocartella ``Documentation``
 2. aggiungete un riferimento ad esso nell'indice (`TOC tree`_) in
    ``Documentation/index.rst``.

 .. _TOC tree: http://www.sphinx-doc.org/en/stable/markup/toctree.html

 Questo, di solito, è sufficiente per la documentazione più semplice (come
 quella che state leggendo ora), ma per una documentazione più elaborata è
 consigliato creare una sottocartella dedicata (o, quando possibile, utilizzarne
 una già esistente). Per esempio, il sottosistema grafico è documentato nella
 sottocartella ``Documentation/gpu``; questa documentazione è divisa in
 diversi file ``.rst`` ed un indice ``index.rst`` (con un ``toctree``
 dedicato) a cui si fa riferimento nell'indice principale.

 Consultate la documentazione di `Sphinx`_ e `reStructuredText`_ per maggiori
 informazione circa le loro potenzialità. In particolare, il
 `manuale introduttivo a reStructuredText`_ di Sphinx è un buon punto da
 cui cominciare. Esistono, inoltre, anche alcuni
 `costruttori specifici per Sphinx`_.

 .. _`manuale introduttivo a reStructuredText`: http://www.sphinx-doc.org/en/stable/rest.html
 .. _`costruttori specifici per Sphinx`: http://www.sphinx-doc.org/en/stable/markup/index.html

 Guide linea per la documentazione del kernel
 --------------------------------------------

 In questa sezione troverete alcune linee guida specifiche per la documentazione
 del kernel:

 * Non esagerate con i costrutti di reStructuredText. Mantenete la
   documentazione semplice. La maggior parte della documentazione dovrebbe
   essere testo semplice con una strutturazione minima che permetta la
   conversione in diversi formati.

 * Mantenete la strutturazione il più fedele possibile all'originale quando
   convertite un documento in formato reStructuredText.

 * Aggiornate i contenuti quando convertite della documentazione, non limitatevi
   solo alla formattazione.

 * Mantenete la decorazione dei livelli di intestazione come segue:

   1. ``=`` con una linea superiore per il titolo del documento::

        ======
        Titolo
        ======

   2. ``=`` per i capitoli::

        Capitoli
        ========

   3. ``-`` per le sezioni::

        Sezioni
        -------

   4. ``~`` per le sottosezioni::

        Sottosezioni
        ~~~~~~~~~~~~

   Sebbene RST non forzi alcun ordine specifico (*Piuttosto che imporre
   un numero ed un ordine fisso di decorazioni, l'ordine utilizzato sarà
   quello incontrato*), avere uniformità dei livelli principali rende più
   semplice la lettura dei documenti.

 * Per inserire blocchi di testo con caratteri a dimensione fissa (codici di
   esempio, casi d'uso, eccetera): utilizzate ``::`` quando non è necessario
   evidenziare la sintassi, specialmente per piccoli frammenti; invece,
   utilizzate ``.. code-block:: <language>`` per blocchi di più lunghi che
   potranno beneficiare dell'avere la sintassi evidenziata.


 Il dominio C
 ------------

 Il **Dominio Sphinx C** (denominato c) è adatto alla documentazione delle API C.
 Per esempio, un prototipo di una funzione:

 .. code-block:: rst

     .. c:function:: int ioctl( int fd, int request )

 Il dominio C per kernel-doc ha delle funzionalità aggiuntive. Per esempio,
 potete assegnare un nuovo nome di riferimento ad una funzione con un nome
 molto comune come ``open`` o ``ioctl``:

 .. code-block:: rst

      .. c:function:: int ioctl( int fd, int request )
         :name: VIDIOC_LOG_STATUS

 Il nome della funzione (per esempio ioctl) rimane nel testo ma il nome del suo
 riferimento cambia da ``ioctl`` a ``VIDIOC_LOG_STATUS``. Anche la voce
 nell'indice cambia in ``VIDIOC_LOG_STATUS`` e si potrà quindi fare riferimento
 a questa funzione scrivendo:

 .. code-block:: rst

      :c:func:`VIDIOC_LOG_STATUS`


 Tabelle a liste
 ---------------

 Raccomandiamo l'uso delle tabelle in formato lista (*list table*). Le tabelle
 in formato lista sono liste di liste. In confronto all'ASCII-art potrebbero
 non apparire di facile lettura nei file in formato testo. Il loro vantaggio è
 che sono facili da creare o modificare e che la differenza di una modifica è
 molto più significativa perché limitata alle modifiche del contenuto.

 La ``flat-table`` è anch'essa una lista di liste simile alle ``list-table``
 ma con delle funzionalità aggiuntive:

 * column-span: col ruolo ``cspan`` una cella può essere estesa attraverso
   colonne successive

 * raw-span: col ruolo ``rspan`` una cella può essere estesa attraverso
   righe successive

 * auto-span: la cella più a destra viene estesa verso destra per compensare
   la mancanza di celle. Con l'opzione ``:fill-cells:`` questo comportamento
   può essere cambiato da *auto-span* ad *auto-fill*, il quale inserisce
   automaticamente celle (vuote) invece che estendere l'ultima.

 opzioni:

 * ``:header-rows:``   [int] conta le righe di intestazione
 * ``:stub-columns:``  [int] conta le colonne di stub
 * ``:widths:``        [[int] [int] ... ] larghezza delle colonne
 * ``:fill-cells:``    invece di estendere automaticamente una cella su quelle
   mancanti, ne crea di vuote.

 ruoli:

 * ``:cspan:`` [int] colonne successive (*morecols*)
 * ``:rspan:`` [int] righe successive (*morerows*)

 L'esempio successivo mostra come usare questo marcatore. Il primo livello della
 nostra lista di liste è la *riga*. In una *riga* è possibile inserire solamente
 la lista di celle che compongono la *riga* stessa. Fanno eccezione i *commenti*
 ( ``..`` ) ed i *collegamenti* (per esempio, un riferimento a
 ``:ref:`last row <last row>``` / :ref:`last row <it last row>`)

 .. code-block:: rst

    .. flat-table:: table title
       :widths: 2 1 1 3

       * - head col 1
         - head col 2
         - head col 3
         - head col 4

       * - column 1
         - field 1.1
         - field 1.2 with autospan

       * - column 2
         - field 2.1
         - :rspan:`1` :cspan:`1` field 2.2 - 3.3

       * .. _`it last row`:

         - column 3

 Che verrà rappresentata nel seguente modo:

    .. flat-table:: table title
       :widths: 2 1 1 3

       * - head col 1
         - head col 2
         - head col 3
         - head col 4

       * - column 1
         - field 1.1
         - field 1.2 with autospan

       * - column 2
         - field 2.1
         - :rspan:`1` :cspan:`1` field 2.2 - 3.3

       * .. _`it last row`:

         - column 3

 .. _it_sphinx_kfigure:

 Figure ed immagini
 ==================

 Se volete aggiungere un'immagine, utilizzate le direttive ``kernel-figure``
 e ``kernel-image``. Per esempio, per inserire una figura di un'immagine in
 formato SVG::

     .. kernel-figure::  ../../../doc-guide/svg_image.svg
        :alt:    una semplice immagine SVG

        Una semplice immagine SVG

 .. _it_svg_image_example:

 .. kernel-figure::  ../../../doc-guide/svg_image.svg
    :alt:    una semplice immagine SVG

    Una semplice immagine SVG

 Le direttive del kernel per figure ed immagini supportano il formato **DOT**,
 per maggiori informazioni

 * DOT: http://graphviz.org/pdf/dotguide.pdf
 * Graphviz: http://www.graphviz.org/content/dot-language

 Un piccolo esempio (:ref:`it_hello_dot_file`)::

   .. kernel-figure::  ../../../doc-guide/hello.dot
      :alt:    ciao mondo

      Esempio DOT

 .. _it_hello_dot_file:

 .. kernel-figure::  ../../../doc-guide/hello.dot
    :alt:    ciao mondo

    Esempio DOT

 Tramite la direttiva ``kernel-render`` è possibile aggiungere codice specifico;
 ad esempio nel formato **DOT** di Graphviz.::

   .. kernel-render:: DOT
      :alt: foobar digraph
      :caption: Codice **DOT** (Graphviz) integrato

      digraph foo {
       "bar" -> "baz";
      }

 La rappresentazione dipenderà dei programmi installati. Se avete Graphviz
 installato, vedrete un'immagine vettoriale. In caso contrario, il codice grezzo
 verrà rappresentato come *blocco testuale* (:ref:`it_hello_dot_render`).

 .. _it_hello_dot_render:

 .. kernel-render:: DOT
    :alt: foobar digraph
    :caption: Codice **DOT** (Graphviz) integrato

    digraph foo {
       "bar" -> "baz";
    }

 La direttiva *render* ha tutte le opzioni della direttiva *figure*, con
 l'aggiunta dell'opzione ``caption``. Se ``caption`` ha un valore allora
 un nodo *figure* viene aggiunto. Altrimenti verrà aggiunto un nodo *image*.
 L'opzione ``caption`` è necessaria in caso si vogliano aggiungere dei
 riferimenti (:ref:`it_hello_svg_render`).

 Per la scrittura di codice **SVG**::

   .. kernel-render:: SVG
      :caption: Integrare codice **SVG**
      :alt: so-nw-arrow

      <?xml version="1.0" encoding="UTF-8"?>
      <svg xmlns="http://www.w3.org/2000/svg" version="1.1" ...>
         ...
      </svg>

 .. _it_hello_svg_render:

 .. kernel-render:: SVG
    :caption: Integrare codice **SVG**
    :alt: so-nw-arrow

    <?xml version="1.0" encoding="UTF-8"?>
    <svg xmlns="http://www.w3.org/2000/svg"
      version="1.1" baseProfile="full" width="70px" height="40px" viewBox="0 0 700 400">
    <line x1="180" y1="370" x2="500" y2="50" stroke="black" stroke-width="15px"/>
    <polygon points="585 0 525 25 585 50" transform="rotate(135 525 25)"/>
    </svg>
	.. include:: ../disclaimer-ita.rst

	.. note:: Per leggere la documentazione originale in inglese:
	:ref:`Documentation/doc-guide/index.rst <doc_guide>`

	.. _it_sphinxdoc:

	Introduzione
	============

	Il kernel Linux usa `Sphinx`_ per la generazione della documentazione a partire
	dai file `reStructuredText`_ che si trovano nella cartella ``Documentation``.
	Per generare la documentazione in HTML o PDF, usate comandi ``make htmldocs`` o
	``make pdfdocs``. La documentazione così generata sarà disponibile nella
	cartella ``Documentation/output``.

	.. _Sphinx: http://www.sphinx-doc.org/
	.. _reStructuredText: http://docutils.sourceforge.net/rst.html

	I file reStructuredText possono contenere delle direttive che permettono di
	includere i commenti di documentazione, o di tipo kernel-doc, dai file
	sorgenti.
	Solitamente questi commenti sono utilizzati per descrivere le funzioni, i tipi
	e l'architettura del codice. I commenti di tipo kernel-doc hanno una struttura
	e formato speciale, ma a parte questo vengono processati come reStructuredText.

	Inoltre, ci sono migliaia di altri documenti in formato testo sparsi nella
	cartella ``Documentation``. Alcuni di questi verranno probabilmente convertiti,
	nel tempo, in formato reStructuredText, ma la maggior parte di questi rimarranno
	in formato testo.

	.. _it_sphinx_install:

	Installazione Sphinx
	====================

	I marcatori ReST utilizzati nei file in Documentation/ sono pensati per essere
	processati da ``Sphinx`` nella versione 1.3 o superiore. Se desiderate produrre
	un documento PDF è raccomandato l'utilizzo di una versione superiore alle 1.4.6.

	Esiste uno script che verifica i requisiti Sphinx. Per ulteriori dettagli
	consultate :ref:`it_sphinx-pre-install`.

	La maggior parte delle distribuzioni Linux forniscono Sphinx, ma l'insieme dei
	programmi e librerie è fragile e non è raro che dopo un aggiornamento di
	Sphinx, o qualche altro pacchetto Python, la documentazione non venga più
	generata correttamente.

	Un modo per evitare questo genere di problemi è quello di utilizzare una
	versione diversa da quella fornita dalla vostra distribuzione. Per fare questo,
	vi raccomandiamo di installare Sphinx dentro ad un ambiente virtuale usando
	``virtualenv-3`` o ``virtualenv`` a seconda di come Python 3 è stato
	pacchettizzato dalla vostra distribuzione.

	.. note::

	#) Le versioni di Sphinx inferiori alla 1.5 non funzionano bene
	con il pacchetto Python docutils versione 0.13.1 o superiore.
	Se volete usare queste versioni, allora dovere eseguire
	``pip install 'docutils==0.12'``.

	#) Viene raccomandato l'uso del tema RTD per la documentazione in HTML.
	A seconda della versione di Sphinx, potrebbe essere necessaria
	l'installazione tramite il comando ``pip install sphinx_rtd_theme``.

	#) Alcune pagine ReST contengono delle formule matematiche. A causa del
	modo in cui Sphinx funziona, queste espressioni sono scritte
	utilizzando LaTeX. Per una corretta interpretazione, è necessario aver
	installato texlive con i pacchetti amdfonts e amsmath.

	Riassumendo, se volete installare la versione 1.4.9 di Sphinx dovete eseguire::

	$ virtualenv sphinx_1.4
	$ . sphinx_1.4/bin/activate
	(sphinx_1.4) $ pip install -r Documentation/sphinx/requirements.txt

	Dopo aver eseguito ``. sphinx_1.4/bin/activate``, il prompt cambierà per
	indicare che state usando il nuovo ambiente. Se aprite un nuova sessione,
	prima di generare la documentazione, dovrete rieseguire questo comando per
	rientrare nell'ambiente virtuale.

	Generazione d'immagini
	----------------------

	Il meccanismo che genera la documentazione del kernel contiene un'estensione
	capace di gestire immagini in formato Graphviz e SVG (per maggior informazioni
	vedere :ref:`it_sphinx_kfigure`).

	Per far si che questo funzioni, dovete installare entrambe i pacchetti
	Graphviz e ImageMagick. Il sistema di generazione della documentazione è in
	grado di procedere anche se questi pacchetti non sono installati, ma il
	risultato, ovviamente, non includerà le immagini.

	Generazione in PDF e LaTeX
	--------------------------

	Al momento, la generazione di questi documenti è supportata solo dalle
	versioni di Sphinx superiori alla 1.4.

	Per la generazione di PDF e LaTeX, avrete bisogno anche del pacchetto
	``XeLaTeX`` nella versione 3.14159265

	Per alcune distribuzioni Linux potrebbe essere necessario installare
	anche una serie di pacchetti ``texlive`` in modo da fornire il supporto
	minimo per il funzionamento di ``XeLaTeX``.

	.. _it_sphinx-pre-install:

	Verificare le dipendenze Sphinx
	-------------------------------

	Esiste uno script che permette di verificare automaticamente le dipendenze di
	Sphinx. Se lo script riesce a riconoscere la vostra distribuzione, allora
	sarà in grado di darvi dei suggerimenti su come procedere per completare
	l'installazione::

	$ ./scripts/sphinx-pre-install
	Checking if the needed tools for Fedora release 26 (Twenty Six) are available
	Warning: better to also install "texlive-luatex85".
	You should run:

	sudo dnf install -y texlive-luatex85
	/usr/bin/virtualenv sphinx_1.4
	. sphinx_1.4/bin/activate
	pip install -r Documentation/sphinx/requirements.txt

	Can't build as 1 mandatory dependency is missing at ./scripts/sphinx-pre-install line 468.

	L'impostazione predefinita prevede il controllo dei requisiti per la generazione
	di documenti html e PDF, includendo anche il supporto per le immagini, le
	espressioni matematiche e LaTeX; inoltre, presume che venga utilizzato un
	ambiente virtuale per Python. I requisiti per generare i documenti html
	sono considerati obbligatori, gli altri sono opzionali.

	Questo script ha i seguenti parametri:

	``--no-pdf``
	Disabilita i controlli per la generazione di PDF;

	``--no-virtualenv``
	Utilizza l'ambiente predefinito dal sistema operativo invece che
	l'ambiente virtuale per Python;


	Generazione della documentazione Sphinx
	=======================================

	Per generare la documentazione in formato HTML o PDF si eseguono i rispettivi
	comandi ``make htmldocs`` o ``make pdfdocs``. Esistono anche altri formati
	in cui è possibile generare la documentazione; per maggiori informazioni
	potere eseguire il comando ``make help``.
	La documentazione così generata sarà disponibile nella sottocartella
	``Documentation/output``.

	Ovviamente, per generare la documentazione, Sphinx (``sphinx-build``)
	dev'essere installato. Se disponibile, il tema Read the Docs per Sphinx
	verrà utilizzato per ottenere una documentazione HTML più gradevole.
	Per la documentazione in formato PDF, invece, avrete bisogno di ``XeLaTeX`
	e di ``convert(1)`` disponibile in ImageMagick (https://www.imagemagick.org).
	Tipicamente, tutti questi pacchetti sono disponibili e pacchettizzati nelle
	distribuzioni Linux.

	Per poter passare ulteriori opzioni a Sphinx potete utilizzare la variabile
	make ``SPHINXOPTS``. Per esempio, se volete che Sphinx sia più verboso durante
	la generazione potete usare il seguente comando ``make SPHINXOPTS=-v htmldocs``.

	Potete eliminare la documentazione generata tramite il comando
	``make cleandocs``.

	Scrivere la documentazione
	==========================

	Aggiungere nuova documentazione è semplice:

	1. aggiungete un file ``.rst`` nella sottocartella ``Documentation``
	2. aggiungete un riferimento ad esso nell'indice (`TOC tree`_) in
	``Documentation/index.rst``.

	.. _TOC tree: http://www.sphinx-doc.org/en/stable/markup/toctree.html

	Questo, di solito, è sufficiente per la documentazione più semplice (come
	quella che state leggendo ora), ma per una documentazione più elaborata è
	consigliato creare una sottocartella dedicata (o, quando possibile, utilizzarne
	una già esistente). Per esempio, il sottosistema grafico è documentato nella
	sottocartella ``Documentation/gpu``; questa documentazione è divisa in
	diversi file ``.rst`` ed un indice ``index.rst`` (con un ``toctree``
	dedicato) a cui si fa riferimento nell'indice principale.

	Consultate la documentazione di `Sphinx`_ e `reStructuredText`_ per maggiori
	informazione circa le loro potenzialità. In particolare, il
	`manuale introduttivo a reStructuredText`_ di Sphinx è un buon punto da
	cui cominciare. Esistono, inoltre, anche alcuni
	`costruttori specifici per Sphinx`_.

	.. _`manuale introduttivo a reStructuredText`: http://www.sphinx-doc.org/en/stable/rest.html
	.. _`costruttori specifici per Sphinx`: http://www.sphinx-doc.org/en/stable/markup/index.html

	Guide linea per la documentazione del kernel
	--------------------------------------------

	In questa sezione troverete alcune linee guida specifiche per la documentazione
	del kernel:

	* Non esagerate con i costrutti di reStructuredText. Mantenete la
	documentazione semplice. La maggior parte della documentazione dovrebbe
	essere testo semplice con una strutturazione minima che permetta la
	conversione in diversi formati.

	* Mantenete la strutturazione il più fedele possibile all'originale quando
	convertite un documento in formato reStructuredText.

	* Aggiornate i contenuti quando convertite della documentazione, non limitatevi
	solo alla formattazione.

	* Mantenete la decorazione dei livelli di intestazione come segue:

	1. ``=`` con una linea superiore per il titolo del documento::

	======
	Titolo
	======

	2. ``=`` per i capitoli::

	Capitoli
	========

	3. ``-`` per le sezioni::

	Sezioni
	-------

	4. ``~`` per le sottosezioni::

	Sottosezioni
	~~~~~~~~~~~~

	Sebbene RST non forzi alcun ordine specifico (*Piuttosto che imporre
	un numero ed un ordine fisso di decorazioni, l'ordine utilizzato sarà
	quello incontrato*), avere uniformità dei livelli principali rende più
	semplice la lettura dei documenti.

	* Per inserire blocchi di testo con caratteri a dimensione fissa (codici di
	esempio, casi d'uso, eccetera): utilizzate ``::`` quando non è necessario
	evidenziare la sintassi, specialmente per piccoli frammenti; invece,
	utilizzate ``.. code-block:: <language>`` per blocchi di più lunghi che
	potranno beneficiare dell'avere la sintassi evidenziata.


	Il dominio C
	------------

	Il Dominio Sphinx C (denominato c) è adatto alla documentazione delle API C.
	Per esempio, un prototipo di una funzione:

	.. code-block:: rst

	.. c:function:: int ioctl( int fd, int request )

	Il dominio C per kernel-doc ha delle funzionalità aggiuntive. Per esempio,
	potete assegnare un nuovo nome di riferimento ad una funzione con un nome
	molto comune come ``open`` o ``ioctl``:

	.. code-block:: rst

	.. c:function:: int ioctl( int fd, int request )
	:name: VIDIOC_LOG_STATUS

	Il nome della funzione (per esempio ioctl) rimane nel testo ma il nome del suo
	riferimento cambia da ``ioctl`` a ``VIDIOC_LOG_STATUS``. Anche la voce
	nell'indice cambia in ``VIDIOC_LOG_STATUS`` e si potrà quindi fare riferimento
	a questa funzione scrivendo:

	.. code-block:: rst

	:c:func:`VIDIOC_LOG_STATUS`


	Tabelle a liste
	---------------

	Raccomandiamo l'uso delle tabelle in formato lista (list table). Le tabelle
	in formato lista sono liste di liste. In confronto all'ASCII-art potrebbero
	non apparire di facile lettura nei file in formato testo. Il loro vantaggio è
	che sono facili da creare o modificare e che la differenza di una modifica è
	molto più significativa perché limitata alle modifiche del contenuto.

	La ``flat-table`` è anch'essa una lista di liste simile alle ``list-table``
	ma con delle funzionalità aggiuntive:

	* column-span: col ruolo ``cspan`` una cella può essere estesa attraverso
	colonne successive

	* raw-span: col ruolo ``rspan`` una cella può essere estesa attraverso
	righe successive

	* auto-span: la cella più a destra viene estesa verso destra per compensare
	la mancanza di celle. Con l'opzione ``:fill-cells:`` questo comportamento
	può essere cambiato da auto-span ad auto-fill, il quale inserisce
	automaticamente celle (vuote) invece che estendere l'ultima.

	opzioni:

	* ``:header-rows:`` [int] conta le righe di intestazione
	* ``:stub-columns:`` [int] conta le colonne di stub
	* ``:widths:`` [[int] [int] ... ] larghezza delle colonne
	* ``:fill-cells:`` invece di estendere automaticamente una cella su quelle
	mancanti, ne crea di vuote.

	ruoli:

	* ``:cspan:`` [int] colonne successive (morecols)
	* ``:rspan:`` [int] righe successive (morerows)

	L'esempio successivo mostra come usare questo marcatore. Il primo livello della
	nostra lista di liste è la riga. In una riga è possibile inserire solamente
	la lista di celle che compongono la riga stessa. Fanno eccezione i commenti
	( ``..`` ) ed i collegamenti (per esempio, un riferimento a
	``:ref:`last row <last row>``` / :ref:`last row <it last row>`)

	.. code-block:: rst

	.. flat-table:: table title
	:widths: 2 1 1 3

	* - head col 1
	- head col 2
	- head col 3
	- head col 4

	* - column 1
	- field 1.1
	- field 1.2 with autospan

	* - column 2
	- field 2.1
	- :rspan:`1` :cspan:`1` field 2.2 - 3.3

	* .. _`it last row`:

	- column 3

	Che verrà rappresentata nel seguente modo:

	.. flat-table:: table title
	:widths: 2 1 1 3

	* - head col 1
	- head col 2
	- head col 3
	- head col 4

	* - column 1
	- field 1.1
	- field 1.2 with autospan

	* - column 2
	- field 2.1
	- :rspan:`1` :cspan:`1` field 2.2 - 3.3

	* .. _`it last row`:

	- column 3

	.. _it_sphinx_kfigure:

	Figure ed immagini
	==================

	Se volete aggiungere un'immagine, utilizzate le direttive ``kernel-figure``
	e ``kernel-image``. Per esempio, per inserire una figura di un'immagine in
	formato SVG::

	.. kernel-figure:: ../../../doc-guide/svg_image.svg
	:alt: una semplice immagine SVG

	Una semplice immagine SVG

	.. _it_svg_image_example:

	.. kernel-figure:: ../../../doc-guide/svg_image.svg
	:alt: una semplice immagine SVG

	Una semplice immagine SVG

	Le direttive del kernel per figure ed immagini supportano il formato DOT,
	per maggiori informazioni

	* DOT: http://graphviz.org/pdf/dotguide.pdf
	* Graphviz: http://www.graphviz.org/content/dot-language

	Un piccolo esempio (:ref:`it_hello_dot_file`)::

	.. kernel-figure:: ../../../doc-guide/hello.dot
	:alt: ciao mondo

	Esempio DOT

	.. _it_hello_dot_file:

	.. kernel-figure:: ../../../doc-guide/hello.dot
	:alt: ciao mondo

	Esempio DOT

	Tramite la direttiva ``kernel-render`` è possibile aggiungere codice specifico;
	ad esempio nel formato DOT di Graphviz.::

	.. kernel-render:: DOT
	:alt: foobar digraph
	:caption: Codice DOT (Graphviz) integrato

	digraph foo {
	"bar" -> "baz";
	}

	La rappresentazione dipenderà dei programmi installati. Se avete Graphviz
	installato, vedrete un'immagine vettoriale. In caso contrario, il codice grezzo
	verrà rappresentato come blocco testuale (:ref:`it_hello_dot_render`).

	.. _it_hello_dot_render:

	.. kernel-render:: DOT
	:alt: foobar digraph
	:caption: Codice DOT (Graphviz) integrato

	digraph foo {
	"bar" -> "baz";
	}

	La direttiva render ha tutte le opzioni della direttiva figure, con
	l'aggiunta dell'opzione ``caption``. Se ``caption`` ha un valore allora
	un nodo figure viene aggiunto. Altrimenti verrà aggiunto un nodo image.
	L'opzione ``caption`` è necessaria in caso si vogliano aggiungere dei
	riferimenti (:ref:`it_hello_svg_render`).

	Per la scrittura di codice SVG::

	.. kernel-render:: SVG
	:caption: Integrare codice SVG
	:alt: so-nw-arrow

	<?xml version="1.0" encoding="UTF-8"?>
	<svg xmlns="http://www.w3.org/2000/svg" version="1.1" ...>
	...
	</svg>

	.. _it_hello_svg_render:

	.. kernel-render:: SVG
	:caption: Integrare codice SVG
	:alt: so-nw-arrow

	<?xml version="1.0" encoding="UTF-8"?>
	<svg xmlns="http://www.w3.org/2000/svg"
	version="1.1" baseProfile="full" width="70px" height="40px" viewBox="0 0 700 400">
	<line x1="180" y1="370" x2="500" y2="50" stroke="black" stroke-width="15px"/>
	<polygon points="585 0 525 25 585 50" transform="rotate(135 525 25)"/>
	</svg>