Documentation/translations/it_IT/doc-guide/sphinx.rst

   1 .. include:: ../disclaimer-ita.rst
   2
   3 .. note:: Per leggere la documentazione originale in inglese:
   4           :ref:`Documentation/doc-guide/index.rst <doc_guide>`
   5
   6 Introduzione
   7 ============
   8
   9 Il kernel Linux usa `Sphinx`_ per la generazione della documentazione a partire
  10 dai file `reStructuredText`_ che si trovano nella cartella ``Documentation``.
  11 Per generare la documentazione in HTML o PDF, usate comandi ``make htmldocs`` o
  12 ``make pdfdocs``. La documentazione così generata sarà disponibile nella
  13 cartella ``Documentation/output``.
  14
  15 .. _Sphinx: http://www.sphinx-doc.org/
  16 .. _reStructuredText: http://docutils.sourceforge.net/rst.html
  17
  18 I file reStructuredText possono contenere delle direttive che permettono di
  19 includere i commenti di documentazione, o di tipo kernel-doc, dai file
  20 sorgenti.
  21 Solitamente questi commenti sono utilizzati per descrivere le funzioni, i tipi
  22 e l'architettura del codice. I commenti di tipo kernel-doc hanno una struttura
  23 e formato speciale, ma a parte questo vengono processati come reStructuredText.
  24
  25 Inoltre, ci sono migliaia di altri documenti in formato testo sparsi nella
  26 cartella ``Documentation``. Alcuni di questi verranno probabilmente convertiti,
  27 nel tempo, in formato reStructuredText, ma la maggior parte di questi rimarranno
  28 in formato testo.
  29
  30 .. _it_sphinx_install:
  31
  32 Installazione Sphinx
  33 ====================
  34
  35 I marcatori ReST utilizzati nei file in Documentation/ sono pensati per essere
  36 processati da ``Sphinx`` nella versione 1.3 o superiore. Se desiderate produrre
  37 un documento PDF è raccomandato l'utilizzo di una versione superiore alle 1.4.6.
  38
  39 Esiste uno script che verifica i requisiti Sphinx. Per ulteriori dettagli
  40 consultate :ref:`it_sphinx-pre-install`.
  41
  42 La maggior parte delle distribuzioni Linux forniscono Sphinx, ma l'insieme dei
  43 programmi e librerie è fragile e non è raro che dopo un aggiornamento di
  44 Sphinx, o qualche altro pacchetto Python, la documentazione non venga più
  45 generata correttamente.
  46
  47 Un modo per evitare questo genere di problemi è quello di utilizzare una
  48 versione diversa da quella fornita dalla vostra distribuzione. Per fare questo,
  49 vi raccomandiamo di installare Sphinx dentro ad un ambiente virtuale usando
  50 ``virtualenv-3`` o ``virtualenv`` a seconda di come Python 3 è stato
  51 pacchettizzato dalla vostra distribuzione.
  52
  53 .. note::
  54
  55    #) Le versioni di Sphinx inferiori alla 1.5 non funzionano bene
  56       con il pacchetto Python docutils versione 0.13.1 o superiore.
  57       Se volete usare queste versioni, allora dovere eseguire
  58       ``pip install 'docutils==0.12'``.
  59
  60    #) Viene raccomandato l'uso del tema RTD per la documentazione in HTML.
  61       A seconda della versione di Sphinx, potrebbe essere necessaria
  62       l'installazione tramite il comando ``pip install sphinx_rtd_theme``.
  63
  64    #) Alcune pagine ReST contengono delle formule matematiche. A causa del
  65       modo in cui Sphinx funziona, queste espressioni sono scritte
  66       utilizzando LaTeX. Per una corretta interpretazione, è necessario aver
  67       installato texlive con i pacchetti amdfonts e amsmath.
  68
  69 Riassumendo, se volete installare la versione 1.4.9 di Sphinx dovete eseguire::
  70
  71        $ virtualenv sphinx_1.4
  72        $ . sphinx_1.4/bin/activate
  73        (sphinx_1.4) $ pip install -r Documentation/sphinx/requirements.txt
  74
  75 Dopo aver eseguito ``. sphinx_1.4/bin/activate``, il prompt cambierà per
  76 indicare che state usando il nuovo ambiente. Se aprite un nuova sessione,
  77 prima di generare la documentazione, dovrete rieseguire questo comando per
  78 rientrare nell'ambiente virtuale.
  79
  80 Generazione d'immagini
  81 ----------------------
  82
  83 Il meccanismo che genera la documentazione del kernel contiene un'estensione
  84 capace di gestire immagini in formato Graphviz e SVG (per maggior informazioni
  85 vedere :ref:`it_sphinx_kfigure`).
  86
  87 Per far si che questo funzioni, dovete installare entrambe i pacchetti
  88 Graphviz e ImageMagick. Il sistema di generazione della documentazione è in
  89 grado di procedere anche se questi pacchetti non sono installati, ma il
  90 risultato, ovviamente, non includerà le immagini.
  91
  92 Generazione in PDF e LaTeX
  93 --------------------------
  94
  95 Al momento, la generazione di questi documenti è supportata solo dalle
  96 versioni di Sphinx superiori alla 1.4.
  97
  98 Per la generazione di PDF e LaTeX, avrete bisogno anche del pacchetto
  99 ``XeLaTeX`` nella versione 3.14159265
 100
 101 Per alcune distribuzioni Linux potrebbe essere necessario installare
 102 anche una serie di pacchetti ``texlive`` in modo da fornire il supporto
 103 minimo per il funzionamento di ``XeLaTeX``.
 104
 105 .. _it_sphinx-pre-install:
 106
 107 Verificare le dipendenze Sphinx
 108 -------------------------------
 109
 110 Esiste uno script che permette di verificare automaticamente le dipendenze di
 111 Sphinx. Se lo script riesce a riconoscere la vostra distribuzione, allora
 112 sarà in grado di darvi dei suggerimenti su come procedere per completare
 113 l'installazione::
 114
 115         $ ./scripts/sphinx-pre-install
 116         Checking if the needed tools for Fedora release 26 (Twenty Six) are available
 117         Warning: better to also install "texlive-luatex85".
 118         You should run:
 119
 120                 sudo dnf install -y texlive-luatex85
 121                 /usr/bin/virtualenv sphinx_1.4
 122                 . sphinx_1.4/bin/activate
 123                 pip install -r Documentation/sphinx/requirements.txt
 124
 125         Can't build as 1 mandatory dependency is missing at ./scripts/sphinx-pre-install line 468.
 126
 127 L'impostazione predefinita prevede il controllo dei requisiti per la generazione
 128 di documenti html e PDF, includendo anche il supporto per le immagini, le
 129 espressioni matematiche e LaTeX; inoltre, presume che venga utilizzato un
 130 ambiente virtuale per Python. I requisiti per generare i documenti html
 131 sono considerati obbligatori, gli altri sono opzionali.
 132
 133 Questo script ha i seguenti parametri:
 134
 135 ``--no-pdf``
 136         Disabilita i controlli per la generazione di PDF;
 137
 138 ``--no-virtualenv``
 139         Utilizza l'ambiente predefinito dal sistema operativo invece che
 140         l'ambiente virtuale per Python;
 141
 142
 143 Generazione della documentazione Sphinx
 144 =======================================
 145
 146 Per generare la documentazione in formato HTML o PDF si eseguono i rispettivi
 147 comandi ``make htmldocs`` o ``make pdfdocs``. Esistono anche altri formati
 148 in cui è possibile generare la documentazione; per maggiori informazioni
 149 potere eseguire il comando ``make help``.
 150 La documentazione così generata sarà disponibile nella sottocartella
 151 ``Documentation/output``.
 152
 153 Ovviamente, per generare la documentazione, Sphinx (``sphinx-build``)
 154 dev'essere installato. Se disponibile, il tema *Read the Docs* per Sphinx
 155 verrà utilizzato per ottenere una documentazione HTML più gradevole.
 156 Per la documentazione in formato PDF, invece, avrete bisogno di ``XeLaTeX`
 157 e di ``convert(1)`` disponibile in ImageMagick (https://www.imagemagick.org).
 158 Tipicamente, tutti questi pacchetti sono disponibili e pacchettizzati nelle
 159 distribuzioni Linux.
 160
 161 Per poter passare ulteriori opzioni a Sphinx potete utilizzare la variabile
 162 make ``SPHINXOPTS``. Per esempio, se volete che Sphinx sia più verboso durante
 163 la generazione potete usare il seguente comando ``make SPHINXOPTS=-v htmldocs``.
 164
 165 Potete eliminare la documentazione generata tramite il comando
 166 ``make cleandocs``.
 167
 168 Scrivere la documentazione
 169 ==========================
 170
 171 Aggiungere nuova documentazione è semplice:
 172
 173 1. aggiungete un file ``.rst`` nella sottocartella ``Documentation``
 174 2. aggiungete un riferimento ad esso nell'indice (`TOC tree`_) in
 175    ``Documentation/index.rst``.
 176
 177 .. _TOC tree: http://www.sphinx-doc.org/en/stable/markup/toctree.html
 178
 179 Questo, di solito, è sufficiente per la documentazione più semplice (come
 180 quella che state leggendo ora), ma per una documentazione più elaborata è
 181 consigliato creare una sottocartella dedicata (o, quando possibile, utilizzarne
 182 una già esistente). Per esempio, il sottosistema grafico è documentato nella
 183 sottocartella ``Documentation/gpu``; questa documentazione è divisa in
 184 diversi file ``.rst`` ed un indice ``index.rst`` (con un ``toctree``
 185 dedicato) a cui si fa riferimento nell'indice principale.
 186
 187 Consultate la documentazione di `Sphinx`_ e `reStructuredText`_ per maggiori
 188 informazione circa le loro potenzialità. In particolare, il
 189 `manuale introduttivo a reStructuredText`_ di Sphinx è un buon punto da
 190 cui cominciare. Esistono, inoltre, anche alcuni
 191 `costruttori specifici per Sphinx`_.
 192
 193 .. _`manuale introduttivo a reStructuredText`: http://www.sphinx-doc.org/en/stable/rest.html
 194 .. _`costruttori specifici per Sphinx`: http://www.sphinx-doc.org/en/stable/markup/index.html
 195
 196 Guide linea per la documentazione del kernel
 197 --------------------------------------------
 198
 199 In questa sezione troverete alcune linee guida specifiche per la documentazione
 200 del kernel:
 201
 202 * Non esagerate con i costrutti di reStructuredText. Mantenete la
 203   documentazione semplice. La maggior parte della documentazione dovrebbe
 204   essere testo semplice con una strutturazione minima che permetta la
 205   conversione in diversi formati.
 206
 207 * Mantenete la strutturazione il più fedele possibile all'originale quando
 208   convertite un documento in formato reStructuredText.
 209
 210 * Aggiornate i contenuti quando convertite della documentazione, non limitatevi
 211   solo alla formattazione.
 212
 213 * Mantenete la decorazione dei livelli di intestazione come segue:
 214
 215   1. ``=`` con una linea superiore per il titolo del documento::
 216
 217        ======
 218        Titolo
 219        ======
 220
 221   2. ``=`` per i capitoli::
 222
 223        Capitoli
 224        ========
 225
 226   3. ``-`` per le sezioni::
 227
 228        Sezioni
 229        -------
 230
 231   4. ``~`` per le sottosezioni::
 232
 233        Sottosezioni
 234        ~~~~~~~~~~~~
 235
 236   Sebbene RST non forzi alcun ordine specifico (*Piuttosto che imporre
 237   un numero ed un ordine fisso di decorazioni, l'ordine utilizzato sarà
 238   quello incontrato*), avere uniformità dei livelli principali rende più
 239   semplice la lettura dei documenti.
 240
 241 * Per inserire blocchi di testo con caratteri a dimensione fissa (codici di
 242   esempio, casi d'uso, eccetera): utilizzate ``::`` quando non è necessario
 243   evidenziare la sintassi, specialmente per piccoli frammenti; invece,
 244   utilizzate ``.. code-block:: <language>`` per blocchi di più lunghi che
 245   potranno beneficiare dell'avere la sintassi evidenziata.
 246
 247
 248 Il dominio C
 249 ------------
 250
 251 Il **Dominio Sphinx C** (denominato c) è adatto alla documentazione delle API C.
 252 Per esempio, un prototipo di una funzione:
 253
 254 .. code-block:: rst
 255
 256     .. c:function:: int ioctl( int fd, int request )
 257
 258 Il dominio C per kernel-doc ha delle funzionalità aggiuntive. Per esempio,
 259 potete assegnare un nuovo nome di riferimento ad una funzione con un nome
 260 molto comune come ``open`` o ``ioctl``:
 261
 262 .. code-block:: rst
 263
 264      .. c:function:: int ioctl( int fd, int request )
 265         :name: VIDIOC_LOG_STATUS
 266
 267 Il nome della funzione (per esempio ioctl) rimane nel testo ma il nome del suo
 268 riferimento cambia da ``ioctl`` a ``VIDIOC_LOG_STATUS``. Anche la voce
 269 nell'indice cambia in ``VIDIOC_LOG_STATUS`` e si potrà quindi fare riferimento
 270 a questa funzione scrivendo:
 271
 272 .. code-block:: rst
 273
 274      :c:func:`VIDIOC_LOG_STATUS`
 275
 276
 277 Tabelle a liste
 278 ---------------
 279
 280 Raccomandiamo l'uso delle tabelle in formato lista (*list table*). Le tabelle
 281 in formato lista sono liste di liste. In confronto all'ASCII-art potrebbero
 282 non apparire di facile lettura nei file in formato testo. Il loro vantaggio è
 283 che sono facili da creare o modificare e che la differenza di una modifica è
 284 molto più significativa perché limitata alle modifiche del contenuto.
 285
 286 La ``flat-table`` è anch'essa una lista di liste simile alle ``list-table``
 287 ma con delle funzionalità aggiuntive:
 288
 289 * column-span: col ruolo ``cspan`` una cella può essere estesa attraverso
 290   colonne successive
 291
 292 * raw-span: col ruolo ``rspan`` una cella può essere estesa attraverso
 293   righe successive
 294
 295 * auto-span: la cella più a destra viene estesa verso destra per compensare
 296   la mancanza di celle. Con l'opzione ``:fill-cells:`` questo comportamento
 297   può essere cambiato da *auto-span* ad *auto-fill*, il quale inserisce
 298   automaticamente celle (vuote) invece che estendere l'ultima.
 299
 300 opzioni:
 301
 302 * ``:header-rows:``   [int] conta le righe di intestazione
 303 * ``:stub-columns:``  [int] conta le colonne di stub
 304 * ``:widths:``        [[int] [int] ... ] larghezza delle colonne
 305 * ``:fill-cells:``    invece di estendere automaticamente una cella su quelle
 306   mancanti, ne crea di vuote.
 307
 308 ruoli:
 309
 310 * ``:cspan:`` [int] colonne successive (*morecols*)
 311 * ``:rspan:`` [int] righe successive (*morerows*)
 312
 313 L'esempio successivo mostra come usare questo marcatore. Il primo livello della
 314 nostra lista di liste è la *riga*. In una *riga* è possibile inserire solamente
 315 la lista di celle che compongono la *riga* stessa. Fanno eccezione i *commenti*
 316 ( ``..`` ) ed i *collegamenti* (per esempio, un riferimento a
 317 ``:ref:`last row <last row>``` / :ref:`last row <it last row>`)
 318
 319 .. code-block:: rst
 320
 321    .. flat-table:: table title
 322       :widths: 2 1 1 3
 323
 324       * - head col 1
 325         - head col 2
 326         - head col 3
 327         - head col 4
 328
 329       * - column 1
 330         - field 1.1
 331         - field 1.2 with autospan
 332
 333       * - column 2
 334         - field 2.1
 335         - :rspan:`1` :cspan:`1` field 2.2 - 3.3
 336
 337       * .. _`it last row`:
 338
 339         - column 3
 340
 341 Che verrà rappresentata nel seguente modo:
 342
 343    .. flat-table:: table title
 344       :widths: 2 1 1 3
 345
 346       * - head col 1
 347         - head col 2
 348         - head col 3
 349         - head col 4
 350
 351       * - column 1
 352         - field 1.1
 353         - field 1.2 with autospan
 354
 355       * - column 2
 356         - field 2.1
 357         - :rspan:`1` :cspan:`1` field 2.2 - 3.3
 358
 359       * .. _`it last row`:
 360
 361         - column 3
 362
 363 .. _it_sphinx_kfigure:
 364
 365 Figure ed immagini
 366 ==================
 367
 368 Se volete aggiungere un'immagine, utilizzate le direttive ``kernel-figure``
 369 e ``kernel-image``. Per esempio, per inserire una figura di un'immagine in
 370 formato SVG::
 371
 372     .. kernel-figure::  ../../../doc-guide/svg_image.svg
 373        :alt:    una semplice immagine SVG
 374
 375        Una semplice immagine SVG
 376
 377 .. _it_svg_image_example:
 378
 379 .. kernel-figure::  ../../../doc-guide/svg_image.svg
 380    :alt:    una semplice immagine SVG
 381
 382    Una semplice immagine SVG
 383
 384 Le direttive del kernel per figure ed immagini supportano il formato **DOT**,
 385 per maggiori informazioni
 386
 387 * DOT: http://graphviz.org/pdf/dotguide.pdf
 388 * Graphviz: http://www.graphviz.org/content/dot-language
 389
 390 Un piccolo esempio (:ref:`it_hello_dot_file`)::
 391
 392   .. kernel-figure::  ../../../doc-guide/hello.dot
 393      :alt:    ciao mondo
 394
 395      Esempio DOT
 396
 397 .. _it_hello_dot_file:
 398
 399 .. kernel-figure::  ../../../doc-guide/hello.dot
 400    :alt:    ciao mondo
 401
 402    Esempio DOT
 403
 404 Tramite la direttiva ``kernel-render`` è possibile aggiungere codice specifico;
 405 ad esempio nel formato **DOT** di Graphviz.::
 406
 407   .. kernel-render:: DOT
 408      :alt: foobar digraph
 409      :caption: Codice **DOT** (Graphviz) integrato
 410
 411      digraph foo {
 412       "bar" -> "baz";
 413      }
 414
 415 La rappresentazione dipenderà dei programmi installati. Se avete Graphviz
 416 installato, vedrete un'immagine vettoriale. In caso contrario, il codice grezzo
 417 verrà rappresentato come *blocco testuale* (:ref:`it_hello_dot_render`).
 418
 419 .. _it_hello_dot_render:
 420
 421 .. kernel-render:: DOT
 422    :alt: foobar digraph
 423    :caption: Codice **DOT** (Graphviz) integrato
 424
 425    digraph foo {
 426       "bar" -> "baz";
 427    }
 428
 429 La direttiva *render* ha tutte le opzioni della direttiva *figure*, con
 430 l'aggiunta dell'opzione ``caption``. Se ``caption`` ha un valore allora
 431 un nodo *figure* viene aggiunto. Altrimenti verrà aggiunto un nodo *image*.
 432 L'opzione ``caption`` è necessaria in caso si vogliano aggiungere dei
 433 riferimenti (:ref:`it_hello_svg_render`).
 434
 435 Per la scrittura di codice **SVG**::
 436
 437   .. kernel-render:: SVG
 438      :caption: Integrare codice **SVG**
 439      :alt: so-nw-arrow
 440
 441      <?xml version="1.0" encoding="UTF-8"?>
 442      <svg xmlns="http://www.w3.org/2000/svg" version="1.1" ...>
 443         ...
 444      </svg>
 445
 446 .. _it_hello_svg_render:
 447
 448 .. kernel-render:: SVG
 449    :caption: Integrare codice **SVG**
 450    :alt: so-nw-arrow
 451
 452    <?xml version="1.0" encoding="UTF-8"?>
 453    <svg xmlns="http://www.w3.org/2000/svg"
 454      version="1.1" baseProfile="full" width="70px" height="40px" viewBox="0 0 700 400">
 455    <line x1="180" y1="370" x2="500" y2="50" stroke="black" stroke-width="15px"/>
 456    <polygon points="585 0 525 25 585 50" transform="rotate(135 525 25)"/>
 457    </svg>