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