diff options
Diffstat (limited to 'Documentation/translations/it_IT/doc-guide/sphinx.rst')
| -rw-r--r-- | Documentation/translations/it_IT/doc-guide/sphinx.rst | 457 |
1 files changed, 457 insertions, 0 deletions
diff --git a/Documentation/translations/it_IT/doc-guide/sphinx.rst b/Documentation/translations/it_IT/doc-guide/sphinx.rst new file mode 100644 index 000000000..474b7e127 --- /dev/null +++ b/Documentation/translations/it_IT/doc-guide/sphinx.rst @@ -0,0 +1,457 @@ +.. include:: ../disclaimer-ita.rst + +.. note:: Per leggere la documentazione originale in inglese: + :ref:`Documentation/doc-guide/index.rst <doc_guide>` + +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> |