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