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